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Preface 


This manual describes how to program Xlib routines using the VAX 
binding. VMS DECwindows provides the VAX binding for Xlib 
programmers who want to adhere to the VAX calling standard. For 
information about the standard, see the Introduction to VMS System 
Routines in the VMS operating system documentation set. 


The manual includes an overview of Xlib and tutorials that show how to 
use Xlib routines. 


Intended Audience 


This manual is intended for experienced programmers who need to learn 
graphics programming using Xlib routines. Readers should be familiar 
with a high-level language. The manual requires minimal knowledge of 
graphics programming. 


Document Structure 


This manual is organized as follows: 


e Chapter 1 provides an overview of Xlib, a sample Xlib program, and a 
guide to debugging Xlib programs. 


¢ Chapters 2 through 9 provide tutorials that show how to use Xlib 
routines and include descriptions of predefined Xlib data structures 
and code examples that illustrate the concepts described. 


This manual also includes the following appendixes: 
e Appendix A is a guide to using the VMS DECwindows font compiler. 


¢ Appendix B lists routines that require Xlib to issue protocol requests 
to the server. 


e Appendix C lists the VMS DECwindows named colors. 
¢ Appendix D lists VMS DECwindows fonts. 





Associated Documents 
The following documents contain additional information: 


¢ VMS DECwindows Guide to Application Programming—Provides an 
overview of programming in the VMS DECwindows environment and 
a guide to programming the XUI Toolkit 


¢ VMS DECwindows Xlib Routines Reference Manual—Provides detailed 
descriptions of each Xlib routine . 


e¢ XUI Style Guide—Describes the standard XUI user interface 
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Conventions 


The following conventions are used in this manual: 


mouse 


MBi, MB2, MB3 


Ctrl/x 


boidface text 


italic text 


UPPERCASE TEXT 


numbers 


XX 


The term mouse is used to refer to any pointing 
device, such as a mouse, a puck, or a stylus. 


MB1 indicates the left mouse button, MB2 indicates 
the middle mouse button, and MB3 indicates the right 
mouse button. (The buttons can be redefined by the 
user.) 


A sequence such as Ctrl/x indicates that you must 
hold down the key labeled Ctrl while you press 
another key or a pointing device button. 


A vertical ellipsis indicates the omission of items from 
a code example or command format; the items are 
Omitted because they are not important to the topic 
being discussed. 


in format descriptions, brackets indicate that whatever 
is enclosed within the brackets is optional; you can 
select none, one, or ail of the choices. (Brackets are 
not, however, optional in the syntax of a directory 
name in a file specification or in the syntax of a 
substring specification in an assignment statement.) 


Boldface text represents the introduction of a new 
term or the name of an argument, an attribute, or a 
reason. 


Italic text represents information that can vary in 
system messages (for example, Internal error 
number). Italic text is also used to represent a 
client-defined routine. 


Uppercase letters indicate that you must enter a 
command (for example, enter OPEN/READ), or they 
indicate the name of a routine, the name of a file, the 
name of a file protection code, or the abbreviation for 
a system privilege. 


Hyphens in coding examples indicate that additional 
arguments to the request are provided on the line that 
follows. 


Unless otherwise noted, all numbers in the text are 
assumed to be decimal. Nondecimal radixes—binary, 
octal, or hexadecimal—are explicitly indicated. 


1 Programming Overview of Xlib 


The VMS DECwindows programming environment includes Xlib, a library 
of low-level routines that enable the VMS DECwindows programmer to 
perform windowing and graphics operations. 


This chapter provides the following: 

e =©An overview of the library 

e A description of error handling conditions 

e Xlib debugging techniques 

Additionally, the chapter includes an introductory Xlib program. The 


program includes annotations that are explained more completely in the 
programming descriptions in later chapters of this guide. 





1.1 Overview of Xlib 


The VMS DECwindows programming environment enables application 
programs, called clients, to interact with workstations using the 

X Window System, Version 11 protocol. The program that controls 
workstation devices such as screens and pointing devices is the server. 
Xlib is a library of routines that enables a client to communicate with the 
server to create and manage the following: 


¢ Connections between clients and the server 

¢ Windows 

¢ Colors 

¢ Graphics characteristics such as line width and line style 
¢ Graphics 

¢ Cursors 

¢ Fonts and text 

¢ Pixmaps and offscreen images 

e Windowing and sending graphics between clients 


¢ Client notification of windowing and graphics operations 


Xlib processes some client requests, such as requests to measure the width 
of a character string, within the Xlib library. It sends other client requests, 
such as those pertaining to putting graphics on a screen or receiving device 
input, to the server. 


The server returns information to clients through either replies or events. 
Replies and events both return information to clients; the server returns 
replies synchronously and events asynchronously. 


1.2 


1.2.1 


Programming Overview of Xlib 
1.1 Overview of Xlib 


Appendix B lists routines that cause Xlib to send requests to the server. 


Figure 1—1 illustrates the relationships among client, Xlib, and server. 
The client calls Xlib routines, which always reside on the client system. 
If possible, Xlib processes calls internally and returns information to 

the client when appropriate. When an Xlib function requires server 
intervention, Xlib generates a request and sends the request to the server. 


The server may or may not reside on the same system as the client 
and Xlib. In either case, Xlib communicates with the server through a 
transport protocol, which can be either local shared memory or DECnet. 


Figure 1-1 Client, Xlib, and Server 
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Sample Xlib Program 


The introductory Xlib program described in Example 1—1 illustrates the 
structure of a typical client program that uses Xlib windowing and graphic 
operations. The program creates two windows, draws text in one of them, 
and exits if the user clicks any mouse button while the cursor is in the 
window containing text. 


This section describes the program and introduces fundamental concepts 
about Xlib resources, windowing, and event-handling. 


Initializing Xlib Resources 


The sample program begins by creating Xlib resources that the client 
needs in order to perform tasks. Xlib resources include windows, fonts, 
pixmaps, cursors, color maps, and data structures that define the 
characteristics of graphics objects. The sample program uses a default 
font, default cursor, default color map, client-defined windows, and a 
client-defined data structure that specifies the characteristics of the text 
displayed. 


The program first makes a connection between the client and the server. 
The client-server connection is the display. After making the connection, 
or opening the display, the client can get display information from the 
server. For example, immediately after opening the display, the program 


calls the DEFAULT SCREEN OF DISPLAY routine to get the identifier of 
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the default screen. The program uses the identifier as an argument in a 
variety of routines it calls later. 


1.2.1.1 Creating Windows 
A window is an area of the screen that either receives input or both 
receives input and displays graphics. 


Windows in the X Window System are hierarchically related. At the base 
of the hierarchy is the root window. All windows that a client creates 
after opening a display are inferiors of the root window. The sample 
program includes two inferiors of the root window. First-generation 
inferiors of a window are its children. The root window has one child, 
identified in the sample as WINDOW_1. The window named WINDOW_2 
is an inferior of the root window and a child of WINDOW_1. 


To complete the window genealogy, all windows created before a specified 
window and hierarchically related to it are its ancestors. In the sample 
program, WINDOW_1 has one ancestor (the root window); WINDOW_2 has 
two ancestors (the root window and WINDOW_1). 


1.2.1.2 Defining Colors 
Defining background and foreground colors is part of the process 
of creating windows in the sample program. The DEFINE_COLOR 
subroutine allocates named VMS DECwindows colors for client use 
in a way that permits other clients to share the same color resource. 
For example, the routine specifies the VMS DECwindows color named 
“light grey” as the background color of WINDOW_2. If other clients were 
using VMS DECwindows color resources, they too could access the VMS 
DECwindows data structure that defines “light grey.” Sharing enables 
clients to use color resources efficiently. - 


The program calls the DEFINE_COLOR subroutine again in the next 
step of initialization, creating the graphics context that defines the 
characteristics of a graphics object. In this case, the program defines 
foreground and background colors used when writing text. 


1.2.1.3 Working with the Window Manager 
Most clients run on systems that have a window manager, which is an Xlib 
application that controls conflicts between clients. The window manager 
also provides the user with control of the appearance of the window session 
screen. Clients provide the window manager with information about how 
it should treat client resources, although the manager can ignore the 
information. The sample program provides the window manager with 
information about the size and placement of WINDOW_1. Additionally, 
the program assigns a name that the window manager displays in the title 
bar of WINDOW_1. 


1 2.1.4 Making Windows Visible on the Screen 
Creating windows does not make them visible. To make its windows 
visible, a client must map them, painting the windows on a specified 
screen. The last step of initializing the sample program is to map 
WINDOW_1 and WINDOW_2. 


1.2.2 
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The core of an Xlib program is a loop in which the client waits for the 
server to notify it of an event, which is a report of either a change in 
the state of a device or the execution of a routine call by another client. 
The server can report 30 types of events associated with the following 
occurrences: 


e Key presses and releases 

¢ Pointer motion 

¢ Window entries and exits 

e Changes of keyboards receiving input 

¢ Changes in keyboard configuration 

¢ Window and graphics exposures 

e Changes in window hierarchy and configuration 
¢ Requests by other clients to change windows 

¢ Changes in available color resources 


¢ Communication from other clients 


When an event occurs, the server sends information about the event to 
Xlib. Xlib stores the information in a data structure. If the client has 
specified an interest in that kind of event, Xlib puts the data structure on 
an event queue. The sample program polls the event queue to determine 
if it contains an event of interest to the client. When the program finds an 
event that is of interest to the client, the program performs a task. 


Because Xlib clients do their essential work in response to events, they are 
event driven. 


The sample program continually checks its event queue to determine if 
a window has been made visible or a button has been clicked. When the 
server informs it of either kind of event, the program performs its real 
work, as follows. 


If a window has been made visible, the server reports a window exposure 
event. Upon receiving this type of event, the program determines whether 
the window exposed is WINDOW_2, and if the event is the first instance 
of the exposure. If both conditions are true, the program writes a message 
into the window. 


If the event reported is a button press, the program checks to make certain 
the cursor is in WINDOW_2 when the user clicks the mouse button. If 
the user clicks the mouse button when the cursor is in WINDOW_1, the 
program reminds the user to click on WINDOW_2. Otherwise, the program 
initiates a series of shutdown routines. 


The shutdown routines unmap WINDOW_1 and WINDOW_2, free 
resources allocated for the windows, break the connection between the 
sample program and its server, and exit the system. 
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On the VMS operating system, clients only need to call SYS$EXIT. Exiting 
the system causes the other shutdown operations to occur. The call to 
SYS$EXIT breaks the connection between client and server, which frees 
resources allocated for client windows, and so forth. 


See Example 1-1 for the sample Xlib program. 


Example 1-1 Sample Program 





PROGRAM SAMPLE PROGRAM 


INCLUDE ’ SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 


DPY ! 
SCREEN 
WINDOW_1, WINDOW _2 ! 
ATTR_MASK ! 
GC ! 
FONT ! 
DEFINE COLOR 
WINDOW 1X, WINDOW_ly ! 
DEPTH 
STATUS, FUNC 
STATE 


RECORD /X$VISUAL/ VISUAL 
RECORD Ls 
RECORD /X$GC_VALUES/ XGCVL 

RECORD /X$SIZE_HINTS/ XSZHN 


RECORD /X$EVENT/ EVENT 
CHARACTER*19 WINDOW _NAME 


/X$SET_WIN_ATTRIBUTES/ XSWDA 


display id 
screen id 
window id 
attributes mask 
gc id 

font id 

color function 
window origin 
number of planes 
synchronous behavior 
flag for text 


! visual type 

! window attributes 
! gc values 

! hints 

! input event 


DATA WINDOW NAME /’Sample Xlib Program’ / 


CHARACTER*60 FONT NAME 
DATA FONT_NAME 


1 /'-ADOBE-NEW CENTURY SCHOOLBOOK-MEDIUM-R-NORMAL~~*~140—-*-*—-P—*! / 


CHARACTER*19 MESSAGE (2) 


DATA MESSAGE /’Click here to exit ’, 


PARAMETER. a 
1 WINDOW 2W 
1 WINDOW 2X 


STATE = 1 


o°20°0 


DPY = X$OPEN_ DISPLAY () 
IF (DPY .EQ. 0) THEN 
WRITE (6, *) 
CALL SYSSEXIT(%VAL (1) ) 
END IF 
SCREEN = 


STATUS 


Create the WINDOW_1 window 


aaa © 


WINDOW_1X = 
WINDOW _1Y 


'Click HERE to exit!’/ 


WINDOW _1W = 400, WINDOW_1H = 300, 
300, WINDOW 2H = 
50, WINDOW _2Y = 75 


150, 


Initialize display id and screen id 


‘Display not opened!’ 


X$DEFAULT_SCREEN_OF_ DISPLAY (DPY) 


XS$SYNCHRONIZE (DPY,1, FUNC) 


(X$WIDTH OF SCREEN(DPY) - WINDOW lw) / 2 
(X$HEIGHT OF SCREEN(DPY) - WINDOW _1H) / 2 
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DEPTH = XS$DEFAULT_DEPTH_OF_ SCREEN (SCREEN) 
CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 
ATTR_MASK = X$M_CW_EVENT_MASK .OR. X$M_CW_BACK_ PIXEL 


XSWDA.X$L_SWDA_EVENT_MASK = X§$M_| EXPOSURE -OR. X$M_BUTTON_PRESS 
XSWDA. SSI: SWDA _ BACKGROUND | PIXEL = 
1 DEFINE | COLOR (DPY, SCREEN, VISUAL, 1) 


© WINDOW_1 = X$CREATE WINDOW (DPY, 
1 X$ROOT_WINDOW_OF_SCREEN (SCREEN) , 
1 WINDOW 1X, WINDOW_1Y, WINDOW_1W, WINDOW_1H, 0, 
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


Cc 
Cc Create the WINDOW_2 window 
Cc 
XSWDA.X$L_SWDA_BACKGROUND_PIXEL = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 2) 
WINDOW_2 = XSCREATE WINDOW(DPY, WINDOW _1, 
1 WINDOW_2X, WINDOW_2Y, WINDOW 2W, WINDOW | 2H, 4, 
1 DEPTH, X$C_INPUT | OUTPUT, VISUAL, ATTR_MASK, XSWDA) 
Cc 
Cc Create graphics context 
€ 
XGCVL. X$L_ GCVL_FOREGROUND = 
ue DEFINE COLOR (DPY, SCREEN, VISUAL, 3) 
XGCVL.X$L_GCVL_BACKGROUND = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 2) 
4) GC = X$CREATE GC(DPY, WINDOW 2, 
a (X$M_GC_FOREGROUND .OR. X$SM_GC_BACKGROUND), XGCVL) 
Cc 
Cc Load the font for text writing 
Cc 
5] FONT = XSLOAD_FONT(DPY, FONT NAME) 
CALL X$SET_FONT(DPY, GC, FONT) 
Cc 
c Define the size and name of the WINDOW_1 window 
Cc 
XSZHN.X$L_SZHN _X = 362 
XSZHN.X$L_SZHN_Y = 282 
XSZHN.X$L_SZHN WIDTH = 400 
XSZHN.X$L_SZHN HEIGHT = 300 
XSZHN.X$L_SZHN_ FLAGS = X$M_P_POSITION .OR. X$M_P_SIZE 
© CALL X$SET_NORMAL HINTS (DPY, WINDOW_1, XSZHN) 
CALL X$STORE_NAME (DPY, WINDOW_1, WINDOW NAME) 
Cc 
Cc Map the windows 
Cc 
@ CALL X$MAP_WINDOW(DPY, WINDOW_1) 


CALL X$MAP_WINDOW(DPY, WINDOW_2) 
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Handle events 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT(DPY, EVENT) 


If this is an expose event on our child window, 
then write the text. 


IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE .AND. 
- EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW _2 THEN 
CALL X$CLEAR_WINDOW(DPY, WINDOW_2) 
CALL X$DRAW_IMAGE_STRING(DPY, WINDOW 2, GC, 
1 75, 75, MESSAGE (STATE) ) 
END IF 


IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON_ PRESS) THEN 
IF (EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW_1) THEN 
STATE = 2 
CALL X$DRAW_IMAGE STRING (DPY, WINDOW_2, GC, 
a 75, 75, MESSAGE (STATE) ) 
ELSE 


Unmap and destroy windows 


CALL XS5UNMAP_WINDOW(DPY, WINDOW_1) 
CALL XSDESTROY_WINDOW(DPY, WINDOW_1) 
CALL X$CLOSE_DISPLAY (DPY) 
CALL SYSSEXIT (%VAL (1) ) 
END IF 
END IF 
END DO 


END 


Create color 


INTEGER*4 FUNCTION DEFINE COLOR(DISP, SCRN, VISU, N) 
INCLUDE ’SYSS$LIBRARY : DECWS$XLIBDEF’ 


INTEGER*4 DISP, SCRN, N 

RECORD /X$VISUAL/ VISU 

RECORD /X$COLOR/ SCREEN_COLOR 

INTEGER*4 STR_SIZE, STATUS, COLOR_MAP 

CHARACTER*15 COLOR_NAME (3) 

DATA COLOR_NAME /’DARK SLATE BLUE’, ‘LIGHT GREY ‘, ‘FIREBRICK rd 


IF (VISU.X$L_VISU_CLASS .EQ. X$C_TRUE_COLOR .OR. 

1  VISU.X$L_VISU_CLASS .EQ. X$C_PSEUDO_ COLOR .OR 

1  VISU.X$L_VISU_CLASS .EQ. X$C_DIRECT COLOR .OR. 
1  VISU.X$L_VISU_CLASS .EQ. X$C_STATIC_COLOR) THEN 
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ELSE 


1 


1 
END 


RETU 
END 


COLOR MAP = X$SDEFAULT_COLORMAP_OF_SCREEN (SCRN) 
STATUS = STRSTRIM(COLOR_NAME (N), 
COLOR_NAME(N), STR_SIZE) 
STATUS = X$ALLOC_NAMED_ COLOR (DISP, COLOR_MAP, 
COLOR_NAME (N) (1:STR_SIZE), SCREEN _COLOR) 
IF (STATUS .NE. 0) THEN 
DEFINE COLOR = SCREEN_COLOR.X$L_COLR_PIXEL 
ELSE 
WRITE (6,*) ‘Color not allocated!’ 
CALL LIBSSIGNAL(%VAL (STATUS) ) 
DEFINE_COLOR = 0 
END IF 


IF (N .EQ. 1 .OR. N .EQ. 3) 

DEFINE_COLOR = X$BLACK PIXEL OF SCREEN (DISP) 
IF (N .EQ. 2 ) 

DEFINE COLOR = X$WHITE_PIXEL_OF SCREEN (DISP) 
IF 


RN 


@ For information about connecting client and server, see Chapter 2. 


@ Xlib buffers client requests and sends them to the server 
asynchronously. This sequence causes clients to receive errors 
after they have occurred. When debugging a program, call the 
SYNCHRONIZE routine to enable synchronous error reporting. 
Using the SYNCHRONIZE routine has a serious negative effect on 
performance. Clients should call the routine only when debugging. 
For more information about debugging, see Section 1.4. 


© For information about creating windows, see Chapter 3. 


@ Before drawing a graphics object on the screen, clients must define the 
characteristics of the object. The program defines the foreground and 
background values for writing text. For information about defining 
graphics characteristics, see Chapter 4. 


© The sample program loads a VMS DECwindows font, New Century 
Schoolbook Roman 14, which the program uses to write the text in 
WINDOW_2. For information about loading fonts, see Chapter 8. 


© The program provides the window manager with hints about window 
size and position. For more information about window management, 
see Section 3.5.1. 


@ Mapping windows makes them visible on the screen. For information 
about window mapping, see Chapter 3 


For more information about event handling, see Chapter 9. 


When a client exits a VMS DECwindows program on the VMS 
operating system, the series of calls to unmap and destroy windows 
and close the display occurs automatically. 


© © 
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@® VMS DECwindows includes named colors for the convenience of 
clients. The sample program uses the named colors “dark slate blue,” 
“light grey,” and “firebrick.” It shares the named colors it uses with 
other clients. For information about sharing colors, whether named or 
client-defined, see Chapter 5. For information about defining colors for 
exclusive use, see Section 5.4. For a list of named VMS DECwindows 
colors, see Appendix C. 





1.3 Handling Error Conditions 


Xlib differs from most VMS programming libraries in the way it handles 
error conditions. In particular, Xlib does not perform any validation of 
input arguments when an Xlib routine is called. 


If the input arguments are incorrect, the server usually generates an error 
event when it receives the Xlib request. Unless the client has specified 
an error handler, the server invokes the default Xlib error handler, which 
prints out a diagnostic message and exits. For more information about the 
Xlib error handler, refer to Section 9.13.2. 


In some cases, Xlib signals a fatal access violation (SYS-F-ACCVIO) when 
passed incorrect arguments. This occurs when arguments are missing or 
are passed using the wrong addressing mode (passed by value instead of 
passed by reference). 





1.4 Debugging Xlib Programs 


As noted in Section 1.1, Xlib handles client requests asynchronously. 
Instead of dispatching requests as it receives them, Xlib buffers requests 
to increase communication efficiency. 


Buffering contributes to delays in error reporting. Asynchronous reporting 
enables Xlib and the server to continue processing client requests despite 
the occurrence of errors. However, buffering contributes to the delay 

_ between the occurrence and client notification of an error. 


As a result, programmers who want to step through routines to 

locate errors must override the buffering that causes asynchronous 
communication between client and server. To override buffering, use 
the SYNCHRONIZE routine. Example 1-1 includes a SYNCHRONIZE 
call as a debugging tool. Use the SYNC routine if you are interested in a 
specific call. The SYNC routine flushes the output buffer and then waits 
until all requests have been processed. 


2 Managing the Client-Server Connection 


A client requires one or more servers to process requests and return 
keyboard and mouse input. The server can be located either on the same 
system as the client or at a remote location where it is accessed across a 
network. 


This chapter describes the following topics related to managing the client- 
server connection: 


¢ Overview of the client-server connection 
e Opening and closing a display 
¢ Getting information about a display 


¢ Managing sending requests to the server 


2.1 Overview of the Client-Server Connection 


A client using Xlib makes its first call to open a display. After opening a 
display, the client can get display information from and send requests to 
the server. To increase the efficiency of the client-server connection, Xlib 
buffers client requests. 


To understand the relationship between a display and hardware, consider 
the classroom illustrated in Figure 2-1. The server and an instructor 
client. program are running on the instructor VAXstation, which includes a 
screen, a keyboard, and a mouse. When the instructor opens a display, 
Xlib establishes a connection between the instructor client program 

and the server. The instructor can output graphics on the instructor 
VAXstation screen. 
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Figure 2-1 Graphics Output to Instructor VAXstation 
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If the instructor wants to output graphics to student screens, each student 
VAXstation must be running a server, and the client program must be 
connected to each server, as Figure 2—2 illustrates. Unlike the prior 
example, where the client program opened one display by making an 
internal connection with the server running on the VAXstation, here the 
client program establishes connections with multiple servers. 


Xlib also enables multiple clients to establish connections with one server. 
For example, to output student work on the instructor screen, each 
student must open a display with the server running on the instructor 
VAXstation. 
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Figure 2-2 Graphics Output to Student VAXstations 
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Establishing the Client-Server Connection 


The OPEN DISPLAY routine establishes a connection between the client 
and.the server. The OPEN DISPLAY routine call has the following format: 


display = XSOPEN_DISPLAY (display _name) 


In this call, display_name is a string that specifies the node on which the 
server is running. The display_name argument has the following format: 


hostname: :number.screen 


The elements of the argument are as follows: 


Elements Description 
hostname The host on which the server is running. If the client and server are 


physically running in the same CPU, clients can specify a display 
number of zero. 


number The number of the display on the host machine. 
screen The screen on which client input and output is handled. 


Passing a null argument to the OPEN DISPLAY routine causes Xlib to 
search for the definition of the logical DECW$DISPLAY. If successful, 
OPEN DISPLAY returns a unique identifier of the display. See 
Example 1-1 for an example of defining a display with this method. 
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A display can also be defined by using the DCL command SET DISPLAY. 
Refer to the VMS DECwindows User’s Guide for more information about 
specifying a display. 


2.3 Closing the Client-Server Connection 
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Although Xlib automatically destroys windows and resources related to 

a process when the process exits the server, clients should close their 
connection with a server explicitly. Clients can close the connection using 
the CLOSE DISPLAY routine. CLOSE DISPLAY destroys all windows 
associated with the display and all resources the client has allocated. The 
CLOSE DISPLAY routine call has the following format: 


XSCLOSE_DISPLAY (display) 
For an example of closing a display, see Example 1-1. 


After closing a display, clients should not refer to windows, identifiers, and 
other resources associated with that display. 


When a display is closed automatically or by an explicit call to CLOSE 
DISPLAY, the server does the following: 


e Discards all input events selected by the client. For information about 
input events, see Chapter 9. 


e Ifthe client has marked the keyboard, specific keys, the pointer button, 
the pointer, or the server for its exclusive use, the server releases them 
for use by other clients. 


e Determines what happens to client resources after the display is 
closed. 
If the server is to destroy all client resources, it destroys them as follows: 


e Examines each window in the client save set. The save set is a list of 
windows that other clients are using. If a window is a member of the 
save set, the server reparents the window to an ancestor not created 
by the client. 


e Maps the save set window, if it is unmapped. The server does this 
even if the save set window was not a subwindow of a window created 
by the client. 


¢ Destroys all windows created by the client after examining each in the 
client save set. 


¢ Frees each nonwindow resource (font, pixmap, cursor, color map, and 
graphics context) created by the client. 


¢ Frees all colors and color map entries allocated by the client. 


When the last connection to the server closes and the server is to destroy 
all client resources, the server performs the following additional steps: 
¢ Resets its state as if it had just been started. 


e Deletes all identifiers except predefined names of window 
characteristics. 
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¢ Deletes all information associated with the root window. 


¢ Resets all device maps and attributes (key click, bell volume, 
acceleration) and the server access control list, a list of hosts 
that can run client programs. 


¢ Restores the standard cursors and root tile, which is a pixmap 
replicated to create a window background. 


¢ Restores the default font path. 


¢ Restores input focus to the root window. 


The server does not perform reset operations if a client requests the server 
to retain its resources. 


2.4 Getting Information About the Client-Server Connection. 


After opening a display, clients can get information about the client-server 
connection using routines listed in Table 2-1. Clients can get information 
about client screens using routines listed in Table 2—2. Clients can get 
information about images created on screens using routines listed and 
described in Table 2-3. 


These routines are useful for supplying arguments to other routines. See 
the VMS DECwindows Xlib Routines Reference Manual for the syntax 
of information routines. This programming guide describes the use of 
information routines and provides examples throughout. 


Table 2—1 Client-Server Connection Routines 


Routine Value returned 

ALL PLANES All bits set on. Used as a plane argument to a 
routine. 

BLACK PIXEL Pixel value that yields black on the specified 
screen. 

CONNECTION NUMBER Connection number of the specified display. 

DEFAULT COLORMAP Identifier of the default color map for allocation 
on the specified screen. 

DEFAULT DEPTH Depth in planes of the default root window for 
the specified screen. 

DEFAULT GC Default graphics context for the root window of 
the specified screen. 

DEFAULT ROOT WINDOW Default root window for the specified screen. 

DEFAULT SCREEN Default screen referred to by the OPEN 
DISPLAY routine. 

DEFAULT VISUAL | Default visual data structure for the specified 
screen. 


(continued on next page) 


Managing the Client-Server Connection 


2.4 Getting Information About the Client-Server Connection 


2-6 


Table 2-1 (Cont.) Client-Server Connection Routines 


Routine 


DISPLAY CELLS 


DISPLAY KEYCODES 


DISPLAY MOTION BUFFER SIZE 


DISPLAY PLANES 
DISPLAY STRING 


IMAGE BYTE ORDER 


MAX REQUEST SIZE 
PROTOCOL REVISION 


PROTOCOL VERSION 


Q LENGTH 


ROOT WINDOW 


SCREEN COUNT 
SERVER VENDOR 


VENDOR RELEASE 


WHITE PIXEL 


Table 2-2 Screen Routines 


Routine 


BLACK PIXEL OF SCREEN 
CELLS OF SCREEN 


DEFAULT COLORMAP OF SCREEN 


Value returned 


Number of color map entries on the specified 
screen. 


Minimum or maximum number of keycodes 
supported by the server, which must fall within 
8 and 225 


Size of the motion buffer 
Number of planes on the specified screen. 


String passed when the display was opened. 
The string takes the form 0::NAME. 


Byte order for images for each scanline unit in 
XY format (bitmap) or for each pixel value in 
Z format. If the byte order is least significant 
byte first, the server returns the constant x$c_ 
Isb_first. If the byte order is most significant 
byte first, the server returns the constant x$c_ 
msb_first. 


Size of the maximum request the server allows 


Minor protocol revision number the server is 
using. 


Version number of the protocol associated with 
the display. 


Length of the event queue for the display. 
There may be events that the server has not 
put on the queue. 


Identifier of the root window. 
Number of available screens. 


identifier of the owner of the server 
implementation. 


Release number of the server, which is 
assigned by the vendor. 


Pixel value that yields white on the specified 
screen. 


Value Returned 


Black pixel value of the specified screen. 


Number of color map entries for the specified 
screen. 


Identifier of the default color map of the 
specified screen. 
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Table 2-2 (Cont.) Screen Routines 


Routine 


DEFAULT DEPTH OF SCREEN 
DEFAULT GC OF SCREEN 


DEFAULT SCREEN OF DISPLAY 
DEFAULT VISUAL OF DISPLAY 


DOES BACKING STORE 
‘DOES SAVE UNDERS 


DISPLAY OF SCREEN 
EVENT MASK OF SCREEN 
HEIGHT OF SCREEN 
HEIGHT MM OF SCREEN 
MAX CMAPS OF SCREEN 


MIN CMAPS OF SCREEN 


PLANES OF SCREEN 

ROOT WINDOW OF SCREEN 
SCREEN OF DISPLAY 
VISUAL ID FROM VISUAL 


WHITE PIXEL OF SCREEN 
WIDTH OF SCREEN 
WIDTH MM OF SCREEN 


Value Returned 


Depth in planes of the specified screen. 


Default graphics context of the specified 
screen. 


Default screen of display. 
Default visual type of display. 
Backing store is not supported in this release. 


Either true or false. True indicates the server 
saves the contents of windows that the client 
window obscures. 


Display of the screen. 

Root event mask of the screen. 
Height of screen in pixels. 
Height of screen in millimeters. 


Maximum number of color maps supported by 
the screen. 


Minimum number of color maps supported by 
the screen. 


Number of planes on the screen. 
Root window on the screen. 
Identifier of the specified screen. 


Returns the visual id associated with the 
specified visual. 


White pixel value of the specified screen. 
Width of the screen in pixels. 
Width of the screen in millimeters. 


Table 2-3 Image Format Routines 


Routine 


BITMAP BIT ORDER 


BITMAP PAD 

BITMAP UNIT 
DISPLAY HEIGHT 
DISPLAY HEIGHT MM 
DISPLAY WIDTH 
DISPLAY WIDTH MM 


Value Returned 


The leftmost bit in a bitmap can be either 
the least or most significant bit. This routine 
returns either the constant x$c_Isb_first or the 
constant x$c_msb_first. 


‘Number of bits by which scanlines are padded. 


Size in bits of a bitmap unit. 
Height of the screen in pixels. 
Height of the screen in millimeters. 
Width of the display in pixels. 
Width of the display in millimeters. 
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Managing Requests to the Server 


Instead of sending each request to the server as the client specifies the 
request, Xlib buffers requests and sends them as a block to increase 
the efficiency of client-to-server communication. The routines listed in 
Table 2—4 control how requests are output from the buffer. 


Table 2-4 Output Buffer Routines 


Routine Description 

FLUSH Flushes the buffer. 

SET AFTER FUNCTION Specifies the function the client calls after 
processing each protocol request. 

SYNC Flushes the buffer and waits until the server 


has received and processed all events, 
including errors. Use SYNC to isolate one call 
when debugging. 

SYNCHRONIZE Causes the server to process requests in the 
buffer synchronously. SYNCHRONIZE causes 
Xlib to generate a return after each Xlib routine 
completes. Use it to debug an entire client or 
block. 


Most clients do not need to call the FLUSH routine because the output 
buffer is automatically flushed by calls to event management routines. 
Refer to Chapter 9 for more information about event handling. 
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3 Working with Windows 


Windows receive information from users; they display graphics, text, and 
messages. Xlib enables a client to create multiple windows and define 
window size, location, and visual appearance on one or more screens. 


Conflicts between clients about displaying windows are handled by a 
window manager, which controls the size and placement of windows and, 
in some cases, window characteristics such as title bars and borders. The 
window manager also keeps clients informed about what it is doing with 
their windows. For example, the window manager might tell a client 
that one of its windows has been resized so that the client can reformat 
information displayed in the window. 


This chapter describes the following topics related to windows and the 
window manager: 


¢ Window fundamentals—A discussion of window type, hierarchy, 
position, and visibility 
¢ Creating and destroying windows—How to create and destroy windows 


e Working with the window manager—How to work with the window 
manager to define user information concerning window management 


¢ Mapping and unmapping windows—How to make windows visible on 
the screen 


e Changing window characteristics—How to change the size, position, 
stacking order, and attributes of windows 


¢ Getting information about windows—How to get information about 
window hierarchies, attributes, and geometry 





3.1 Window Fundamentals 


A window is an area of the screen that either receives input or receives 
input and displays graphics. 


One type of window only receives input. Because an input-only window 
does not display text or graphics, it is not visible on the screen. Clients 
can use input-only windows to control cursors, manage input, and define 
regions in which the pointer is used exclusively by one client. 


A second type of window both receives input and displays text and 
graphics. 


Clients can make input-output windows visible on the screen. To make 

a window visible, a client first creates the window and then maps it. 
Mapping a window allows it to become visible on the screen. When more 
than one window is mapped, the windows may overlap. Window hierarchy 
and position on the screen determine whether or not one window hides the 
contents of another window. 
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Window Hierarchy 


Windows that clients create are part of a window hierarchy. The hierarchy 
determines how windows are seen. At the base of the hierarchy is the root 
window, which covers the entire screen when the client opens a display. 
All windows created after opening a display are subwindows of the root 
window. 


When a client creates one or more subwindows of the root window, the root 
window becomes a parent. Children of the root window become parents 
when clients create subwindows of the children. 


The hierarchy is structured like a stack of papers. At the bottom of the 
stack is the root window. Windows that clients create after opening a 
display are stacked on top of the root window, overlapping parts of it. 
For example, the window named child-of-root overlaps parts of the root 
window in Figure 3-1. The child-of-root window always touches the root 
window. Xlib always stacks children on top of the parents. 


Figure 3-1 Root Window and One Child 


Child—of-root 
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If a window has more than one child and if their borders intersect, Xlib 
stacks siblings in the order the client creates them, with the last sibling on 
top. For example, the second-level window named 2nd-child-of-root, which 
was created last, overlaps the second-level window named Ist-child-of-root 
in Figure 3-2. | 
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Figure 3-2 Relationship Between Second-Level Windows 


1st-child—of-root 


2nd—child—of-root 


Root 
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Third-level windows maintain the hierarchical relationships of their 
parents. The child-of-1st-child window overlaps child-of-2nd-child in 
Figure 3-3. 
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Figure 3-3 Relationship Between Third-Level Windows 
Child—of—1st—child 


Child—of-—2nd—child 


Root _——an 
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Windows created before a specified window and hierarchically related to 
it are ancestors of that window. For example, the root window and the 
window named Ist-child-of-root are ancestors of child-of-1st-child-of-root. 


3.1.2 Window Position 


Xlib coordinates define window position on a screen and place graphics 
within windows. Coordinates that specify the position of a window 

are relative to the origin, the upper left corner of the parent window. 
Coordinates that specify the position of a graphic object within a window 
are relative to the origin of the window in which the graphic object is 
displayed. 


Xlib measures length along the x axis from the origin to the right; it 
measures length along the y axis from the origin down. Xlib specifies 
coordinates in units of pixels, the smallest unit the server can display on 
a screen. Figure 3—4 illustrates the Xlib coordinate system. 
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Figure 3-4 Coordinate System 


Parent Origi 
arent Origin Axis 





Child Origin 


ZK-0007A-GE 


For more information about positioning windows, see Section 3.2. For 
more information about positioning graphics, see Chapter 6. 


3.1.3. Window Visibility and Occlusion 


A window is visible if one can see it on the screen. To be visible, a window 
must be an input-output window, it must be mapped, its ancestors must 

be mapped, and it must not be totally hidden by another window. When a 
window and its ancestors are mapped, the window is considered viewable. 
A viewable window that is totally hidden by another window is not visible. 


Even though input-only windows are never visible, they can overlap 
other windows. An input-only window that overlaps another window 
is considered to occlude that window. Specifically, window A occludes 
window B if both are mapped, if A is higher in the stacking order than 
B, and if the rectangle defined by the outside edges of A intersects the 
rectangle defined by the outside edges of B. 


A viewable input-output window that overlaps another window is 
considered to obscure that window. Specifically, window A obscures 
window B if A is a viewable input-output window, if A is higher in the 
stacking order than B, and if the rectangle defined by the outside edges of 
A intersects the rectangle defined by the outside edges of B. 
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Creating Windows 


After opening a display, clients can create windows. As noted in the 
description of window fundamentals (Section 3.1), creating a window does 
not make it visible on a screen. To be visible, the window must meet the 
conditions described in Section 3.1.3. 


Clients can either create windows that inherit most characteristics not 
relating to size or shape from their parents or define all characteristics 
when creating windows. 


Using Attributes of the Parent Window 
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An attribute is a characteristic of a window not relating to size or shape, 
such as the window background color. The CREATE SIMPLE WINDOW 
routine creates an input-output subwindow that inherits the following 
attributes from its parent: 


¢ Method of moving the contents of a window when the parent is moved 
or resized 


¢ Instructions for saving window contents when the window obscures or 
is obscured by another window 


¢ Instructions to the server regarding information that ancestors should 
know when a window change occurs 


¢ Instructions to the window manager concerning map requests 
¢ Color 


¢ Cursor 


For more information about these attributes, see Section 3.2.2. 


If the parent is a root window, the new window created with the CREATE 
SIMPLE WINDOW routine has the following attributes: 


¢ The server discards window contents if the window is reconfigured. 
¢ The server discards the contents of obscured portions of the window. 


¢ The server discards the contents of any window that the new window 
obscures. 


¢ No events are specified as being of interest to the window ancestors. 
¢ No restrictions are placed on the window manager. 
e The color is identical to the parent color. 


¢ No cursor is specified. 


In addition to creating a window with attributes inherited from the parent 
window, the CREATE SIMPLE WINDOW routine enables clients to define 
the border and background attributes of the window and its position and 
size. 
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Example 3-1 illustrates creating a simple window. To make the window 
visible, the example includes mapping and event handling functions, which 
are described in Section 3.4 and Chapter 9. 


Example 3-1 Creating a Simple Window 





INTEGER*4 WINDOW_1 
INTEGER*4 WINDOW_1X, WINDOW_1Y 


0 PARAMETER WINDOW_1W = 600, WINDOW_1H = 600 


WINDOW_1X = (X$DISPLAY_ WIDTH OF SCREEN(SCREEN) - WINDOW _1W) / 2 
WINDOW_1Y = (X$DISPLAY HEIGHT OF SCREEN(SCREEN) - WINDOW_1H) / 2 


WINDOW_1 = X$CREATE SIMPLE WINDOW (DPY, 

1 X$ROOT_WINDOW_OF_SCREEN (SCREEN) , 

1 WINDOW _1X, WINDOW_1lY, WINDOW_1W, WINDOW_1H, 10, 

1 XS$BLACK_PIXEL_OF_ SCREEN(SCREEN), X$WHITE_PIXEL_OF_SCREEN (SCREEN) ) 


@ Assign window width and height the value of 600 (pixels) each. 


@ The client specifies the position of the window using two display 
information routines, DISPLAY WIDTH and DISPLAY HEIGHT. 
The WINDOW_1X and WINDOW_IY coordinates define the top left 
outside corner of the window borders relative to the inside of the 
parent border. In this case, the parent is the root window, which does 
not have a border. 


© The CREATE SIMPLE WINDOW routine call has the following format: 
window_id = XSCREATE SIMPLE WINDOW(display, parent_id, 
x_coord, y_ coord, width, height, border width, 


border_id, background_id) 


The client specifies a black border ten pixels wide, a white background, 
and a size of 600 by 600 pixels. 


The window manager overrides border width and color. 


CREATE SIMPLE WINDOW returns a unique identifier, WINDOW_1, 
used in subsequent calls related to the window. 


3.2.2 Defining Window Attributes 


To create a window whose attributes are different from the parent window, 
use the CREATE WINDOW routine. The CREATE WINDOW routine 
enables clients to specify the following window attributes when creating 
an input-output window: . 


¢ Default contents of an input-output window 
¢ Border of an input-output window 


e Treatment of the window when it or its relative is obscured 
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e Treatment of the window when it or its relative is moved 


¢ Information the window receives about operations associated with 
other windows 


e Color 


e Cursor 


Clients creating input-only windows can define the following attributes: 
¢ Treatment of the window when it or its relative is moved 


_ © Information the window receives about operations associated with 
other windows 


¢ Cursor 
Specifying other attributes for an input-only window causes the server to 


generate an error. Input-only windows cannot have input-output windows 
as children. 


Use the following method to define window attributes: 


¢ Assign values to the relevant members of a set window attributes data 
structure. 


¢ Indicate the defined attribute by specifying the appropriate flag and in 
the value_mask argument of the CREATE WINDOW routine. If more 
than one attribute is to be defined, indicate the attributes by doing 
a bitwise OR on the appropriate flags and passing the result in the 
value_mask argument of the CREATE WINDOW routine. 


Figure 3-5 illustrates the set window attributes data structure. 
Figure 3-5 Set Window Attributes Data Structure 
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Figure 3-5 (Cont.) Set Window Attributes Data Structure 


Table 3-1 describes the members of the data structure. 
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Table 3-1 Set Window Attributes Data Structure Members 


Member Name Contents 





X$L_SWDA_BACKGROUND_PIXMAP Defines the window background of an input-output window. This 
. member can assume one of three possible values: pixmap identifier, 
the constant x$c_none (default), or the constant x$c_parent_relative. 


If the client specifies a pixmap identifier, a pixmap defines the 
_ window background. The pixmap must have the same root and 
number of bits per pixel as the window but can be any size. For 
more information about creating pixmaps, see Chapter 7. 


If the client specifies the constant x$c_none (the default), the 
window has no defined background. If the parent has no defined 
background, neither does the window being created. 


If the client specifies the constant x$c_parent_relative, the 
background of the window is identical to the background of its 
parent. In this case, the window must have the same number of 
bits per pixel as the parent. If the background value of the window 
is x$c_parent_relative and the parent background is x$c_none, the 
window being created has no defined background. The server does 
not copy the parent background; instead, it reexamines the parent 
background each time the client needs the window background. 
For a background that is identical to the parent background, the 
origin of the background tile always aligns with the origin of the 
parent background tile origin. Otherwise, the background tile origin is 
always the window origin. 


(continued on next page) 
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Table 3-1 (Cont.) Set Window Attributes Data Structure Members 


Member Name Contents 








lf the client alters the pixmap after using it for the background, the 
results are unpredictable because the server might either make a — 
copy of the pixmap used to draw the background, or it might refer to 
the pixmap directly. Free the background pixmap when the client no 
longer needs to refer to it. In particular, free the pixmap after setting 
it into the window but before destroying the window. 


When regions of the window are exposed and the server has not 
retained their contents, the server automatically tiles the regions with 
the background pixmanp if the client specified a pixmap identifier or 
the constant x$c_parent_relative. If the client specified the constant 
x$c_none, the server leaves the previous screen contents in place, 
provided the window and its parent have the same number of bits 
per pixel. Otherwise, the initial contents of the exposed region are 
undefined. 


X$L_SWDA_BACKGROUND_PIXEL Specifying a value for the X$__SWDA_BACKGROUND_ 
PIXEL member causes the server to override the X$L_SWDA_ 
BACKGROUND_PIXMAP member. This is equivalent to specifying a 
pixmap of any size filled with the background pixel and used to paint 
the window background. 


X$L_SWDA_BORDER_PIXMAP Defines the window border of an input-output window. The following 
conditions apply: 


¢ The border tile origin is always the same as the background tile 
origin. 

¢ The border pixmap and the window must have the same root 
and the same number of bits per pixel. Otherwise, the server 
issues an error. 

¢ Clients can specify a pixmap of any size. Using some sizes, 
however, increases performance. 

* The default copies the border pixmap from the parent. If the 
client specifies the constant x$c_copy_from_parent, the parent 
border pixmap is copied. The window must have the same 
number of bits per pixel as the parent, or the server issues an 
error. Subsequent changes to the parent do not affect the child. 


If the client alters the pixmap after using it for the border, the results 
are unpredictable because the server may either make a copy of 
the pixmap used to draw the border, or it may refer to the pixmap 
directly. 


Because output to a window is always limited or clipped to the inside 
of the window, graphics operations are never affected by the window 
border. 


X$L_SWDA_BORDER_PIXEL Specifying a value for X$__SWDA_BORDER_PIXEL causes the 
server to override the X$L_SWDA_BORDER_PIXMAP member. This 
is equivalent to specifying a pixmap of any size filled with the border 
pixel and used to paint the window border. 
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Table 3—1 (Cont.) Set Window Attributes Data Structure Members 





Member Name 


Contents 





X$L_SWDA_BIT_GRAVITY 
X$L_SWDA_WIN_GRAVITY 


X$L_SWDA_BACKING_STORE 


X$L_SWDA_BACKING_PLANES 


X$L_SWDA_BACKING_PIXEL 


X$L_SWDA_SAVE_UNDER 


Defines how window contents should be moved when an input-only 
or input-output window is resized. By default, the server does not 
retain window contents. For more information about bit gravity, see 
Section 3.6. te, 


Defines how the server should reposition the newly created input-- 
Only or input-output window when its parent window is resized. By 
default, the server does not move the newly created window. For 
more information about window gravity, see Section 3.6. 


Provides a hint to the server about how the client wants it to manage 
obscured portions of the window. In this release, clients must 
maintain window contents. 


Indicates (with bits set to one) which bit planes of the window hold 
dynamic data that must be preserved if the window obscures or is 
obscured by another window. In this release, clients must maintain 
data to be preserved. 


Defines what values to use in planes not specified by the X$L_ 
SWDA_BACKING_PLANES member. In this release, clients must 
maintain values. 


Setting the X$L_SWDA_SAVE_UNDER member to true informs the 


server that the client would like the contents of the screen saved 


_when an input-output window obscures them. Clients must maintain 
the contents of screens. 


(continued on next page) 
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Table 3-1 (Cont.) Set Window Attributes Data Structure Members 


Member Name Contents 


X$L_SWDA_EVENT_MASK Defines which types of events associated with an input-only or 
input-output window the server should report to the client. For more 
information about defining event types, see Chapter 9. Following are 
events about which the client can state an interest: 


Event Type Description 
Button Motion, button press and release, 
exclusive input 
Color Change in color map 
Window Entry into and exit from a window 
Exposure Exposure of a previously obscured 
window 
Input focus | Change in window that receives keyboard 
input 
Keyboard and keys Change in keyboard state, and key press 
or release 
Pointer Motion 
Property Change in window characteristics 
Structure Notification and control of requests from 
clients 
X$L_SWDA_DO_NOT_PROPAGATE_ Defines which kinds of events should not be propagated to 
MASK ancestors. For more information about managing events, see 
Chapter 9. 
X$L_SWDA_OVERRIDE_REDIRECT Specifies whether calls to map and configure an input-only or 


input-output window should override a request by another client to 
redirect those calls. For more information about redirecting calls, see 
Chapter 9. Typically, this is used to inform a window manager not 
to tamper with the window, such as when the client is creating and 
mapping a menu. 


X$L_SWDA_COLORMAP Specifies the color map, if any, that best reflects the colors of an 
input-output window. The color map must have the same visual type 
as the window. If it does not, the server issues an error. For more 
information about the color map and visual types, see Chapter 5. 


X$L_SWDA_CURSOR Specifying a value for the cursor member causes the server to use a 
particular cursor when the pointer is in an input-only or input-output 
window. 





Table 3-2 lists default values for the set window attributes data 
structure. 
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Table 3-2 Default Values of the Set Window Attributes Data Structure 


Member 


X$L_SWDA_BACKGROUND_PIXMAP 
X$L_SWDA_BACKGROUND_PIXEL 
X$L_SWDA_BORDER_PIXMAP 
X$L_SWDA_BORDER_PIXEL 
X$L_SWDA_BIT_GRAVITY 
X$L_SWDA_WIN_GRAVITY 
X$L_SWDA\BACKING_STORE 
X$L_SWDA_BACKING_PLANES 
X$L_SWDA_BACKING_PIXEL 
X$L_SWDA_SAVE_UNDER 
X$L_SWDA_EVENT_MASK 


X$L_SWDA_DO_NOT_PROPAGATE_ 
MASK 


X$L_SWDA_OVERRIDE_REDIRECT 
X$L_SWDA_COLORMAP 
X$L_SWDA_CURSOR 


Default Value 


None 

Undefined 

Copied from the parent window 
Undefined 

Window conients not retained 
Window not moved 

Window contents not retained 
All 1s 

0 

False 

Empty set 

Empty set 


False 
Copied from parent 
None 


Xlib assigns a flag for each member of the set window attributes data 
structure to facilitate referring to the members, as listed in Table 3-3. 


Table 3-3 Set Window Attributes Data Structure Flags 


Flag Name 


x$m_cw_back_pixmap 
x$m_cw_background_pixel 
x$m_cw_border_pixmap 
x$m_cw_border_pixel 
x$m_cw_bit_gravity 
x$m_cw_win_gravity 
x$m_cw_backing_store 
x$m_cw_backing_planes 
x$m_cw_backing_pixel 
x$m_cw_override_redirect 
x$m_cw_save_under 
x$m_cw_event_mask 


Set Window Attributes Member 


X$L_SWDA_BACKGROUND_PIXMAP 
X$L_SWDA_BACKGROUND_PIXEL 
X$L_SWDA_BORDER_PIXMAP 
X$L_SWDA_BORDER_PIXEL 
X$L_SWDA_BIT_GRAVITY 
X$L_SWDA_WIN_GRAVITY 
X$L_SWDA_BACKING_STORE 
X$L_SWDA_BACKING_PLANES 
X$L_SWDA_BACKING_PIXEL 
X$L_SWDA_OVERRIDE_REDIRECT 
X$L_SWDA_SAVE_UNDER 
X$L_SWDA_EVENT_MASK 


(continued on next page) 
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Table 3-3 (Cont.) Set Window Attributes Data Structure Flags 





Flag Name Set Window Attributes Member 
x$m_cw_dont_propagate X$L_SWDA_DO_NOT_PROPAGATE_MASK 
x$m_cw_colormap X$L_SWDA_COLORMAP 

x$m_cw_cursor X$L_SWDA_CURSOR 





Note that in addition to the mask symbols (x$m_) listed in Table 3-3, the 
Xlib definition files also define the corresponding bit field symbols (x$v_). 


Example 3-2 illustrates how clients can define window attributes while 
creating input-output windows with the CREATE WINDOW routine. 
The program creates a parent window and two children windows. The 
hierarchy of the subwindows is determined by the order in which the 
program creates them. In this case, SUBWINDOW_1 is superior to 
SUBWINDOW_2, which is created last. 


Example 3-2 Defining Attributes When Creating Windows 





INTEGER*4 WINDOW ! window id 
INTEGER*4 SUBWINDOW_1 ! window id 
INTEGER*4 SUBWINDOW_ 2 ! window id 
i) RECORD /X$SET_WIN_ATTRIBUTES/ XSWDA ! window attributes 
PARAMETER WINDOW_W = 600, WINDOW_H = 600, 
1 SUBWINDOW_1X = 150, SUBWINDOW_1Y = 100, 
1 SUBWINDOW_1W = 300, SUBWINDOW 1H = 400, 
a SUBWINDOW_2X = 275, SUBWINDOW_2Y = 125, 
1 SUBWINDOW _2W = 50, SUBWINDOW 2H = 150 
WINDOW_X = (XSWIDTH_OF_SCREEN(SCREEN) - WINDOW _W) / 2 
WINDOW_Y = (X$HEIGHT_OF_SCREEN(SCREEN) - WINDOW_H) / 2 
DEPTH = X$DEFAULT DEPTH_OF_ SCREEN (SCREEN) 
CALL X$DEFAULT_VISUAL_OF_ SCREEN (SCREEN, VISUAL) 
ATTR_MASK = X$M_CW_EVENT MASK .OR. X$M_CW_BACK PIXEL 
2) XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE .OR. X$M_BUTTON_PRESS 
XSWDA.X$L_SWDA_BACKGROUND PIXEL = 
1 DEFINE_COLOR (DPY, SCREEN, VISUAL, 1) 
© WINDOW = XSCREATE_ WINDOW (DPY, 
1 X$ROOT_WINDOW_OF_SCREEN (SCREEN) , 
1 WINDOW X, WINDOW _ Y, WINDOW_W, WINDOW_H, 0, 
ak DEPTH, ~XSC_ INPUT OUTPUT, VISUAL, ATTR_MASK, XSWDA) 
Cc 
Cc Create the SUBWINDOW_1 window 
Cc 


XSWDA.X$L_SWDA_BACKGROUND_PIXEL = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 2) 
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Example 3-2 (Cont.) Defining Attributes When Creating Windows 


aaa 


SUBWINDOW_1 = X$CREATE_WINDOW(DPY, WINDOW, 
1 SUBWINDOW_1X, SUBWINDOW_1Y, SUBWINDOW_1W, SUBWINDOW_1H, 4, 
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


Create the SUBWINDOW_2 window 
XSWDA.X$L_SWDA_BACKGROUND_ PIXEL = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 3) 


SUBWINDOW_2 = XSCREATE_ WINDOW (DPY, WINDOW, 
1 SUBWINDOW_2X, SUBWINDOW_2Y, SUBWINDOW_2W, SUBWINDOW_2H, 4, 
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


INTEGER*4 FUNCTION DEFINE COLOR(DISP, SCRN, VISU, N) 


@ Allocate storage for a set window attributes data structure used to 
define window attributes. 


@ Set the attributes of the parent window. The client indicates an 
interest in window exposure and button press events. For more 
information about events, see Chapter 9. 


- The client defines window background by calling the DEFINE_COLOR 
routine. For more information about defining colors, see Chapter 5. 


© The CREATE WINDOW routine call has the following format: 


window_id_ return=X$CREATE_WINDOW(display, parent_id, 
x coord, y coord, width, height, border _width, 
depth, class, visual_struc, attributes_mask, 
attributes) 


The depth of a window is its number of bits per pixel. The call passes 
a display information routine to indicate that the client wants the 
parent window depth to be identical to the display depth. 


The window class can be either input only or input-output, specified by 
the following constants: 


e x$c_input_only 
¢ x$c_input_output 


If the window is the same class as the parent, pass the constant — 
x$c_copy_from_parent. 


Note that the only attributes clients can define for input-only windows 
are window gravity, event mask, do-not-propagate mask, override 
redirect, and cursor. 


The border width of input-only windows must be zero. 
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The visual type indicates how the window displays color values. For 
more information about visual types, see Chapter 5. 





3.3 Destroying Windows 


When a client no longer needs a window, the client should destroy it using 
either the DESTROY WINDOW or the DESTROY SUBWINDOWS routine. 
DESTROY WINDOW destroys a specified window and all its subwindows. 
DESTROY SUBWINDOWS destroys all subwindows of a specified window 
in bottom to top stacking order. 


Destroying a window frees all storage allocated for that window. If the 
window is mapped to the screen, the server notifies applications using the 
window that it has been destroyed. 


3.4 Mapping and Unmapping Windows 
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After creating a window, the client can map it to a screen using the MAP 
WINDOW or MAP SUBWINDOWS routine. Mapping generally makes a 
window visible at the location the client specified when creating it. Part or 
all of the window is not visible when the following conditions occur: 


¢ One or more windows higher in the stacking order obscures it 
e One or more window ancestors is not mapped 


e The new window extends beyond the boundary of its parent 


MAP WINDOW maps a window. If the window is an inferior, and one 
or more of its ancestors has not been mapped, the server considers the 
window to be mapped after the call, even though the window is not visible 
on the screen. The window becomes visible when its ancestors are mapped. © 


To map all subwindows of a specified window in top to bottom order, use 
MAP SUBWINDOWS. Using the MAP SUBWINDOWS routine to map 
several windows may be more efficient than calling the MAP WINDOW 
routine to map each window. The MAP SUBWINDOWS routine enables 
the server to map all of the windows at one time instead of mapping a 
single window with the MAP WINDOW routine. 


To ensure that the window is completely visible, use the MAP RAISED 
routine. MAP RAISED reorders the stack with the window on top and 
then maps the window. Example 3-3 illustrates how a window is mapped 
and raised to the top of the stack. 
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Example 3-3 Mapping and Raising Windows 


INTEGER*4 WINDOW ! window id 
INTEGER*4 SUBWINDOW_1 ! window id 
INTEGER*4 SUBWINDOW 2 ! window id 
Cc Create windows in the following order: 
Cc WINDOW, SUBWINDOW_2, SUBWINDOW_1 
Cc 
CALL XS$MAP_WINDOW(DPY, WINDOW) 
@ CALL X$MAP_WINDOW(DPY, SUBWINDOW_1) 
e CALL X$MAP_RAISED(DPY, SUBWINDOW 2) 


@ In this example, the client creates SUBWINDOW_1 after 
SUBWINDOW_2, putting SUBWINDOW_1 at the top of the stack. 


Consequently, whether SUBWINDOW_2 were mapped before or after 
SUBWINDOW_1, SUBWINDOW_1 would obscure SUBWINDOW_2. 


The effect is illustrated in Figure 3-6. 


@ Mapping and raising SUBWINDOW_2 moves it to the top of the stack. 
It is now visible, as Figure 3-7 illustrates. 


When the client no longer needs a window mapped to the screen, call 
UNMAP WINDOW. If the window is a parent, its children are no longer 
visible after the call, although they are still mapped. The children become 
visible when the parent is mapped again. 


To unmap all subwindows of a specified window, use UNMAP 
SUBWINDOWS. UNMAP SUBWINDOWS results in an UNMAP 
WINDOW call on all subwindows of the parent, from bottom to top 
stacking order. 





3.5 Associating Properties with Windows 


Xlib enables clients to associate data with a window. This data is 
considered a property of the window. For example, a client could store 
text as a window property. Although a property must be data of only one 
type, it can be stored in 8-bit, 16-bit, and 32-bit formats. 


Xlib uses atoms to name properties. An atom is a string paired with an 
identifier. For example, a client could use the atom X$C_XA_WM_ICON_ 
NAME to name a window icon stored for later use. The atom X$C_XA_ 
WM_ICON_NAME pairs the string X$C_XA_WM_ICON_NAME with a 
value, 25, that uniquely identifies the stored name. 
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Figure 3-6 Window Before Restacking 


SUBWINDOW_1 SUBWINDOW_2 
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In SYS$LIBRARY:DECW$XLIBDEF.H, VMS DECwindows includes 
predefined atoms such as X$C_XA_WM_ICON_NAME for commonly 

used properties. Table 3—4 lists all predefined atoms except those used to 
identify font properties and those used to communicate with the window 
manager. See Table 3-6 for a list of atoms related to window management. 
See Chapter 8 for a list of atoms related to fonts. 
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Figure 3~7 Restacked Window 


SUBWINDOW_1 SUBWINDOW_2 


[El] Restacked Window 
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Table 3-4 Predefined Atoms 


For Global Selection 


X$C_XA_PRIMARY 


For Cut Buffers 


X$C_XA_CUT_BUFFERO 
X$C_XA_CUT_BUFFER2 
X$C_XA_CUT_BUFFER4 
X$C_XA_CUT_BUFFER6 


For Color Maps 


X$C_XA_RGB_COLOR_MAP 
X$C_XA_RGB_BLUE_MAP 
X$C_XA_RGB_GREEN_MAP 
X$C_XA_RGB_DEFAULT_MAP 


For Resources 


X$C_XA_RESOURCE_MANAGER 
X$C_XA_ATOM 
X$C_XA_CARDINAL 
X$C_XA_CURSOR 
X$C_XA_FONT 

X$C_XA_PIXMAP 
X$C_XA_RECTANGLE 
X$C_XA_VISUALID 


X$C_XA_SECONDARY 


X$C_XA_CUT_BUFFER1 
X$C_XA_CUT_BUFFER3 
X$C_XA_CUT_BUFFERS5 
X$C_XA_CUT_BUFFER7 


X$C_XA_RGB_BEST_MAP 
X$C_XA_RGB_RED_MAP 
X$C_XA_RGB_GRAY_MAP 


X$C_XA_ARC 
X$C_XA_BITMAP 
X$C_XA_COLORMAP 
X$C_XA_DRAWABLE 
X$C_XA_INTEGER 
X$C_XA_POINT 
X$C_XA_STRING 
X$C_XA_WINDOW 


In addition to providing predefined atoms, Xlib enables clients to create 
their own atom names. To create an atom name, use the INTERN ATOM 


routine, as in the following example: 


INTEGER*4 ATOM_ID 
INTEGER*4 IF_EXISTS 
CHARACTER*7 ATOM NAME 
DATA ATOM NAME /’MY ATOM’ / 


ATOM_ID = X$INTERN_ATOM(DPY, ATOM_NAME, IF_EXISTS) 
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The routine returns an identifier associated with the string MY_ATOM. 
If the atom does not exist in the atom table, Xlib returns a value of none. 
Note that any atom identifier, and its associated name, remain defined 
until the server is reset. 


To get the name of an atom, use the GET ATOM NAME routine, as in the 
following example: 


CHARACTER*100 ATOM NAME 
INTEGER*4 ATOM _ID, STATUS 


ATOM ID = 19 
STATUS = X$GET_ATOM NAME (DPY, ATOM_ID, ATOM_NAME) 


The routine returns a string associated with the atom identifier, 39. 


Xlib enables clients to change, obtain, update, and interchange properties. 
Example 3—4 illustrates exchanging properties between two subwindows. 

The example uses the CHANGE PROPERTY routine to set a property on 
the parent window and the GET PROPERTY routine to get the data from 
the parent window. 


Example 3-4 Exchanging Window Properties 





aan 


CHARACTER*50 PROPERTY _DATA !Data stored as a property 
CHARACTER*50 PROP !Data stored as a property 
CHARACTER*1000 PROPERTY RETURNED !'Property returned 


RECORD /XSVISUAL/ VISUAL 
RECORD /XSSET WIN ATTRIBUTES/ XSWDA 


RECORD /X$SIZE_HINTS/ XSZHN 


visual type 
window attributes 


! 
: 
RECORD /X$GC_VALUES/ XGCVL ! gc values 
1 
! 


RECORD /XSEVENT/ EVENT 


PARAMETER 


PRP RB 


hints 

input event 
WIN WIDTH = 600, WIN_HEIGHT = 600, 
SUB_WIDTH = 300, SUB HEIGHT = 150, 


WIN X = 100, WIN_Y = 100, 


SUB1_X = 150, SUB1_Y = 100, 
SUB2_X = 150, SUB2_Y = 350, 
OFFSET = 0, LENGTH = 1000 


DATA PROPERTY_DATA /’You clicked MB1’/ 


Create the WINDOW window 


DEPTH = X$DEFAULT_DEPTH_OF_SCREEN (SCREEN) 
CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 


ATTR_MASK 


X$M_CW_EVENT MASK .OR. X$M_CW_BACK_PIXEL 





(continued on next page) 
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Example 3-4 (Cont.) Exchanging Window Properties 





XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE .OR. X$M_BUTTON_PRESS 
if .OR. X$M_PROPERTY_CHANGE 
XSWDA.X$L_SWDA_BACKGROUND_PIXEL = 

1  DEFINE_COLOR(DPY, SCREEN, VISUAL, 1) 


WINDOW = XS$CREATE_WINDOW(DPY, 

1  X$ROOT_WINDOW_OF_SCREEN (SCREEN) , 

1  WIN_X, WIN_Y, WIN WIDTH, WIN HEIGHT, 0, 

1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


Cc 
Cc Create the subwindows 
Cc x 
XSWDA.X$L_SWDA_BACKGROUND_PIXEL = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 2) 
SUBWINDOW1 = X$CREATE WINDOW (DPY, WINDOW, 
1 SUB1_X, SUB1_Y, SUB WIDTH, SUB HEIGHT, 4, 
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 
SUBWINDOW2 = XSCREATE_ WINDOW (DPY, WINDOW, 
1  SUB2_X, SUB2_Y, SUB WIDTH, SUB HEIGHT, 4, 
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 
Cc 
Cc Handle events 
C 
DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT (DPY, EVENT) 
IF (EVENT .EVNT_TYPE -EQ. X$C_EXPOSE -AND. 
1 EVENT .EVNT_EXPOSE.X$L_EXEV_WINDOW -EQ. WINDOW) THEN 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 25, 'Press MB1 in the upper window.’ ) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 50, ‘’To exit, press MB2.’) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT .EVNT_BUTTON.X$L_BTEV_BUTTON -BQ. X$C_BUTTON2) THEN 
CALL SYSSEXIT (%VAL (1) ) 
END IF 
IF (EVENT .EVNT_BUTTON.X$L_BTEV_WINDOW -EQ. SUBWINDOW1 .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON -EQ. X$C_BUTTON1) THEN 
0 CALL XSCHANGE PROPERTY (DPY, WINDOW, X$C_XA_CUT_BUFFERO, 
1 X$C_XA_STRING, 16, X$C_PROP_MODE_REPLACE, 
1 SREF (PROPERTY DATA) , 15) 
END IF 


IF (EVENT.EVNT_TYPE .EQ. X$C_PROPERTY NOTIFY .AND. 
1 EVENT .EVNT_PROPERTY.X$L_PPEV_ATOM .EQ. X$C_XA_CUT_BUFFERO) THEN 





(continued on next page) 
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Example 3—4 (Cont.) Exchanging Window Properties 








@ CALL X$GET_WINDOW PROPERTY (DPY, WINDOW, X$C_XA_CUT BUFFERO, 

if OFFSET, LENGTH, TRUE, X$C_XA STRING, TYPE RETURNED, 

1 FORMAT RETURNED, NUM ITEMS RETURNED, BYTES REMAINING, 

i , REF (1000) , REF (PROPERTY RETURNED) ) 
® CALL X$DRAW_STRING(DPY, SUBWINDOW2, GC, 75, 75, 

i PROPERTY RETURNED, NUM ITEMS RETURNED) 

END IF 
END DO 
END 
@ When the user clicks MB1 in subwindow SUBWINDOW1, the client 


calls the CHANGE PROPERTY routine. CHANGE PROPERTY causes 
the server to change the property identified by the atom X$C_XA_ 
CUT_BUFFERD0O to the value specified by PROPERTY_DATA. The 
property is associated with the parent window, WINDOW. 


When changing properties, the client can specify how the server 
should treat them. If the client specifies the constant x$c_prop_ 
mode_replace, the server discards the previous property. If the client 
specifies the constant x$c_prop_mode_prepend, the server inserts 
the new data at the beginning of the existing property data. If the 
client specifies the constant x$c_prop_mode_append, the server 
inserts the new data at the end of the existing property data. 


Changing the property causes the server to send a property notify 
event to the parent window, WINDOW. For information about event 
handling, see Chapter 9. 


After checking to ensure that the changed property is the one to 
obtain, the client calls the GET WINDOW PROPERTY routine. 
Note that the client returns the property, which is a string type, 
into a buffer of 1000 bytes, specified by the variable PROPERTY_ 
RETURNED. 


After getting the string data from the parent window, the client uses 
it to write text in SUBWINDOW2. For information about writing text, 
see Chapter 8. 


In addition to the GET WINDOW PROPERTY routine, Xlib includes the 
property-management routines described in Table 3-5. 


Table 3-5 Routines for Managing Properties 


Routine Description 
LIST PROPERTIES _ Returns a list of properties defined for a specified 
window. 





(continued on next page) 
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Table 3-5 (Cont.) Routines for Managing Properties 


Routine Description 

ROTATE WINDOW Rotates the properties of a specified window and 

PROPERTIES . generates a property notify event. For more information 
about property notify events, see Chapter 9. 

DELETE PROPERTY Deletes a specified property. 


3.5.1 Using Properties to Communicate with the Window Manager 


Xlib provides predefined atoms to enable clients to communicate hints to 
the window manager about the following: 


¢ Window names 

e Icon names 

e Pixmaps used to define window icons 

¢ Commands used to start the application 

¢ Position and size of windows in their startup state 
¢ Initial state of windows 

¢ Input that windows accept 


¢ Names used to retrieve application resources 


Table 3-6 describes the atom names, data types, and formats of these 
properties. 


Table 3-6 Atom Names of Window Manager Properties 


Atom Data Type Format Description of the Property 
X$C_XA_WM_NAME STRING 8 Application name 
~ X$C_XA_WM_ICON_NAME STRING 8 Icon name 
X$C_XA_WM_NORMAL_HINTS WM_SIZE_HINTS 32 Size hints for a window in its 
normal state 
_X$C_XA_WM_ZOOM_HINTS WM_SIZE_HINTS 32 Size hints for a zoomed window 
X$C_XA_WM_HINTS WM_HINTS 32 Hints about keyboard input, 


initial state, icon pixmap, icon 
window, icon position, and icon 
mask 
X$C_XA_WM_COMMAND STRING 8 Command used to start the 
client 
X$C_XA_WM_ICON_SIZE WM_ICON_SIZE 32 Specifies the icon size 
supported by the window 
manager 


(continued on next page) 
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Table 3-6 (Cont.) Atom Names of Window Manager Properties 


Atom 


X$C_XA_WM_CLASS 


Data Type Format Description of the Property 


STRING 32 Allows window manager to 
obtain the application resources 
from the resource database 


X$C_XA_WM_TRANSIENT_FOR WINDOW 32 Indicates that a window, such 


as a dialog box, is transient 





3.5.1.1 


Xlib provides the following methods for using the properties described in 
Table 3-6 to communicate with the window manager: 


¢ Defining properties with the SET WM HINTS routine—SET WM 
HINTS uses the WM hints data structure to define hints about 
keyboard input, initial state of the window, icon pixmap, icon window, 
icon position, icon mask, and window group. 


¢ Using convenience routines to communicate with the window 
manager—xXlib includes routines that enable clients to communicate 
individual hints about window names, window icon names, and 
window classes. 


¢ Providing and obtaining hints about the size and position of windows— 
Xlib routines communicate information about the size and position of 
windows. 


e Changing the values of a property—Xlib includes a routine to change 
the value of an existing property. 


Note that it is not guaranteed that the window manager will apply window 
manager hints. 


This section describes how to use properties to communicate with the 
window manager. 


Defining Properties Using the SET WM HINTS Routine 


Use the SET WM HINTS routine to provide the window manager with 
hints about keyboard input, initial window state, icon pixmap, icon 
window, icon position, icon mask, and window group. A window manager 
can use the window group property to treat a set of windows as a group. 
For example, if a client manipulates multiple children of the root window, 
SET WM HINTS enables the client to provide enough information so that 
a window manager can make all windows into icons, rather than just one 
window. 


Xlib provides a WM hints data structure that enables clients to easily 
specify these hints. Note, however, that each time the WM hints data _ 
structure is passed to SET WM HINTS, the flags field only specifies which 
fields are valid, not which fields are updated. Setting one flag, and passing 
one value, states that all other values are no longer valid. 
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Figure 3-8 illustrates the wm hints data structure. Table 3—7 describes its 
members. 


Figure 3-8 WM Hints Data Structure 
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Table 3-7 WM Hints Data Structure Members 





Member Name Contents 
X$L_HINT_FLAGS Specifies the members of the data structure that are defined. 
X$L_HINT_INPUT Indicates whether or not the client relies on the window manager to get 
keyboard input. 
X$L_HINT_INITIAL_STATE Defines how the window should appear in its initial configuration. Possible 
initial states are as follows: 
Constant Description 
x$c_dont_care_state Client is not interested in the initial state 
x$c_normal_state Initial state used most often 
x$c_zoom_state Window starts zoomed 
x$c_iconic_state Window starts as an icon 
x$c_inactive_state Window is seldom used 
X$L_HINT_ICON_PIXMAP Identifies the pixmap used to create the window icon. 
X$L_HINT_ICON_WINDOW Specifies the window to be used as an icon. 
X$L_HINT_ICON_X Specifies the initial x-coordinate of the icon position. 
X$L_HINT_ICON_Y Specifies the initial y-coordinate of the icon position. 
X$L_HINT_ICON_MASK Specifies the pixels of the icon pixmap used to create the icon. | 


X$L_HINT_WINDOW_GROUP Specifies that a window belongs to a group of other windows. 
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3.5.1.2 Defining Individual Properties 
Xlib includes routines to enable clients to define individual properties 
for communicating with the window manager about window names, icon 
names, and window classes. 


To define a window name, use the STORE NAME routine. The sample 
program in Chapter 1 uses the STORE NAME routine to define the name 
of its parent window, as follows: 


CALL X$STORE_NAME(DPY, WINDOW_1, 
1 ‘A Sample Xlib Program’ ) 


To get the name of a window, use the FETCH NAME routine. The routine 
either returns the name of the specified window or sets the value of the 
X$C_XA_WM_NAME property to null. 


The SET ICON NAME and GET ICON NAME routines define and get the 
name of a window icon. 


To define and get the class of a specified window, use the SET CLASS 
HINT and GET CLASS HINT routines. The routines refer to the class 
hint data structure illustrated in Figure 3-9. 


Figure 3-9 Class Hint Data Structure 






; 
x$a_chnt_res_class 4 





Table 3—8 describes members of the data structure. 


Table 3-8 Class Hint Data Structure Members 


Member Name Contents 





X$A_CHNT_RES_NAME Defines the name of the window. The name defined in this data structure may 
differ from the name defined by the X$C_XA_WM_NAME property. The X$C_ 
XA_WM_NAME property specifies what should be displayed in the title bar. 
Consequently, it may contain a temporary name, as in the name of a file a client 
currently has in a buffer. In contrast to X$C_XA_WM_NAME, this member defines 
the formal window name that clients should use when retrieving resources from 
the resource database. 


X$A_CHNT_RES_CLASS Defines the class of the window. 


At times, clients may need to indicate to the window manager that a 
top-level window is really only a transient window. For instance, a client 
may communicate to the window manager that the window is a dialog box 
mapped on behalf of another window. To communciate this, a client calls 
the SET TRANSIENT FOR HINT routine. The routine sets the X$C_XA_ 
WM_TRANSIENT_FOR property of the transient window and associates 
the transient window with a main window. To obtain the 
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X$C_XA_WM_TRANSIENT_FOR property for a specified window, call the 
GET TRANSIENT FOR HINT routine. 


To define the command that invokes an application in a specified window, 
use the SET COMMAND routine. 


3.5.1.3 Providing Size Hints 
Xlib provides routines to communicate with the window manager about the 
size and position of windows in their normal and zoomed startup states. 
Use the following method to specify the size and position of a window in 
its usual startup state: 


1 Assign values to the relevant members of the size hints data structure, 
including the X$L_SZHN_FLAGS member. This member specifies 
which members of the data structure are defined. Table 3—9 lists the 
flags. 


2 Call the SET NORMAL HINTS routine 


Table 3-9 Set Window Attributes Data Structure Flags 


Flag Name Size Hints Member 

x$m_p_position User-specified position of the window 

x$m_us_size User-specified size of the window 

x$m_p_position Client-specified position 

x$m_p_size Client-specified size 

x$m_p_min_size Client-specified minimum size of the window 
x$m_p_max_size Client-specified maximum size of the window 
x$m_p_resize_inc Client-specified increments for resizing the window 
x$m_p_aspect Client-specified minimum and maximum aspect ratios 
x$m_p_all_hints The bitwise OR of the following flags: x$m_p_position, x$m_ 


p_size, x$m_p_min_size, x$m_p_max_size, x$m_p_resize_ 
inc, and x$m_p_aspect. 


Figure 3-10 illustrates the size hints data structure. Table 3-10 describes 
its contents. _ 


Figure 3-10 Size Hints Data Structure 












ee id 
teed 
a 
anes id 
a 


(continued on next page) 


3-28 


Working with Windows 
3.5 Associating Properties with Windows 


Figure 3-10 (Cont.) Size Hints Data Structure 
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Table 3-10 Size Hints Data Structure Members 


Member Name 


X$L_SZHN_FLAGS 
X$L_SZHN_X 
X$L_SZHN_Y 
X$L_SZHN_WIDTH 
X$L_SZHN_HEIGHT 
X$L_SZHN_MIN_WIDTH 
X$L_SZHN_MIN_HEIGHT 
X$L_SZHN_MAX_WIDTH 
X$L_SZHN_MAX_HEIGHT 
X$L_SZHN_WIDTH_INC 
X$L_SZHN_HEIGHT_INC 
X$L_SZHN_MNAS_X 


X$L_SZHN_MNAS_Y 


X$L_SZHN_MXAS_X 


Contents 


Defines which members the client is assigning values to. 
Specifies the x-coordinate that defines window position. 
Specifies the y-coordinate that defines window position. 
Defines the width of the window. 

Defines the height of the window. 

Specifies the minimum useful width of the window. 
Specifies the minimum useful height of the window. 
Specifies the maximum useful width of the window. 


- Specifies the maximum useful height of the window. 


Defines the increments by which the width of the window can be resized. 
Defines the increments by which the height of the window can be resized. 


With the X$L_SZHN_MNAS_Y member, specifies the minimum aspect ratio of the 
window. 


With the X$L_SZHN_MNAS_X member, specifies the minimum aspect ratio of the 
window. 


With the X$L_SZHN_MXAS_Y member, specifies the maximum aspect ratio of the 
window. 


(continued on next page) 
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Table 3—10 (Cont.) Size Hints Data Structure Members 


Member Name 


Contents 





X$L_SZHN_MXAS_Y 


With the X$L_SZHN_MXAS_X member, specifies the maximum aspect ratio of the 
window. 


Setting the minimum and maximum aspects indicates the preferred range of the 
size of a window. An aspect is expressed in terms of a ratio between x and y. 


For example, if the minimum aspect of x is 1 and y is 2, and the maximum aspect of 
x is 2 and y is 5, then the minimum window size is a ratio of 1/2, and the maximum 
is a ratio of 2/5. In this case, a window could have a width of 300 pixels and a 
height of 600 pixels minimally, and maximally a width of 600 pixels and a height of 
1500 pixels. 





The following illustrates using the size hints data structure to set the 
normal window manager hints for a window: 


XSZHN.X$L_SZHN X = 362 

XSZHN.X$L_SZHN Y = 282 

XSZHN.X$L_SZHN WIDTH = 400 

XSZHN.X$L_SZHN HEIGHT = 300 

XSZHN.X$L_SZHN FLAGS = X$C_P_POSITION .OR. X$C_P_SIZE 


CALL XSSET_NORMAL HINTS(DPY, WINDOW_1, XSZHN) 


The example sets hints about the size and location hints of WINDOW_1. 
Note, however, that each time the size hints data structure is passed to 
SET NORMAL HINTS, the flags field only specifies which fields are valid, 
not which fields are updated. Setting one flag, and passing one value, 
states that all other values are no longer valid. 


3.5.2 Exchanging Properties Between Clients 


Xlib provides routines that enable clients to exchange properties. The 
properties, which are global to the server, are called selections. Text cut 
from one window and pasted into another window exemplifies the global 
exchange of properties. The text cut in window A is a property owned by 
client A. Ownership of the property transfers to client B, who then pastes 
the text into window B. 


Properties are exchanged between clients by a series of calls to routines 
that manage the selected text. When a user drags the pointer cursor, 
client A responds by calling the SET SELECTION OWNER routine. SET 
SELECTION OWNER identifies client A as the owner of the selected text. 
The routine also identifies the window of the selection, associates an atom 
with the text, and puts a timestamp on the selection. The atom, X$C___ 
XA_PRIMARY, names the selection. The timestamp enables any clients 
competing for the selection to determine selection ownership. 
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Clients can determine the owner of a selection by calling the GET 
SELECTION OWNER routine. This routine returns the identifier of 
the window that currently owns the specified selection. 


By calling the CONVERT SELECTION routine, clients ask the owner of a 
selection to convert it to a particular data type. If conversion is possible, 
the client converting the selection notifies the client requesting the 
conversion that the selection is available. The property is then exchanged. 


For example, when a user decides to paste the selected text in window 
B, client B, who owns window B, sends client A a selection request. The 
request identifies the window requesting the cut text and the format in 
which the client would like the property transferred. 


In response to the request, client A first checks to ensure that the time of 
the request corresponds to the time in which client A owns the selection. 
If the time coincides, and if the selection is in the data type required by 
client B, client A notifies client B that the text is stored and available. The 
text is then moved to client B. 


After receiving the text, client B informs client A that client B is the 
current owner of the selection. 


Clients request and notify other clients of selections by using events. For 
information about using events to request, convert, and notify clients of 
selections, see Chapter 9. For style guidelines about using selections, see 
the XUI Style Guide. 


3.6 Changing Window Characteristics 


Xlib provides routines that enable clients to change window position, size, 
border width, stacking order, and attributes. 


This section describes how to use Xlib routines to do the following: 
¢ Change multiple window characteristics in one call 

¢ Change position, size, or border width | 

e Change stacking order 


¢ Change window attributes 


3.6.1. Reconfiguring Windows 


Xlib enables clients either to change window characteristics using one 
call or to use individual routines to reposition, resize, or to change border 
width. 


The CONFIGURE WINDOW routine enables clients to change window 
position, size, border width, and place in the hierarchy. To change these 
window characteristics in one call, use the CONFIGURE WINDOW 
routine, as follows: 


1 Set values of relevant members of a window changes data structure. 


2 Indicate what is to be reconfigured by specifying the appropriate flag 
in the CONFIGURE WINDOW value_mask argument. 
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The window changes data structure enables clients to specify one or more 
values for reconfiguring a window. Figure 3—11 illustrates the window 
changes data structure. Table 3-11 describes the members of the data 
structure. 


Figure 3-11 Window Changes Data Structure 













‘ 

: 

: 
x$l_wchg_border_width 16 

: 
x$l_wchg_stack_mode 24 

Table 3-11 Window Changes Data Structure Members 

Member Name Contents 

X$L_WCHG_X Defines the x-coordinate of the new location of the window relative to the 


origin of its parent. The x- and y-coordinates specify the upper left outside 
corner of the window. 


X$L_WCHG_Y Defines the y-coordinate of the new location of the window relative to the 
origin of its parent. The x- and y-coordinates specify the upper left outside 
corner of the window. 


X$L_WCHG_WIDTH Defines the new width of the window, excluding the border. 
X$L_WCHG_HEIGHT Defines the new height of the window, excluding the border. 
X$L_WCHG_BORDER_WIDTH Specifies the new window border in pixels. 

X$L_WCHG_SIBLING Specifies the sibling window for stacking order. 
X$L_WCHG_STACK_MODE Defines how the window is restacked. Table 3-12 lists constants and 


definitions for restacking windows. 





The client can change the hierarchical position of a window in relation to 
all windows in the stack or to a specified sibling. If the client changes the 
size, position, and stacking order of the window by calling CONFIGURE 
WINDOW, the server restacks the window based on its final, not initial, 
size and position. Table 3—12 lists constants and definitions for restacking 
windows. 
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Table 3-12 Stacking Values 


Constants 


x$c_above 
x$c_below 
x$c_top_if 


x$c_bottom_if 


x$c_opposite 


Relative to All 


Top of stack. 
Bottom of stack. 


If any sibling obscures a window, the server 
places the obscured window on top of the 
stack. 


If a window obscures any sibling, the server 
places the obscuring window at the bottom 
of the stack. 


If any sibling obscures a window, the server 
places the obscured window on top of the 
stack. If a window obscures any window, 
the server places the obscuring window at 
the bottom of the stack. 


Relative to Sibling 


Just above sibling. 
Just below sibling. 


If the specified sibling obscures a window, the 
server places the obscured window at the top of 
the stack. 


If the window obscures the specified sibling, the 
server places the obscuring window at the bottom 
of the stack. 


if the specified sibling obscures a window, the 
server places the obscuring window on top of the 
stack. If a window obscures the specified sibling, 
the server places the obscuring window on the 
bottom of the stack. 


Xlib assigns a symbol to the flag associated with each member of the data 


structure (Table 3~13). 


Table 3-13 Window Changes Data Structure Flags 


Flag Name 


x$m_cw_x 

x$m_cw_y 
x$m_cw_width 
x$m_cw_height 
x$m_cw_border_width 
x$m_cw_sibling 
x$m_cw_stack_mode 


Window Changes Member 


X$L_WCHG_X 

X$L_WCHG_Y 
X$L_WCHG_WIDTH 
X$L_WCHG_HEIGHT 
X$L_WCHG_BORDER_WIDTH 
X$L_WCHG_SIBLING 
X$L_WCHG_STACK_MODE 


Example 3-5 illustrates using CONFIGURE WINDOW to change the 
position, size, and stacking order of a window when the user presses a 


button. 
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Example 3-5 Reconfiguring a Window 


Cc 
Cc 
Cc 
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This program changes the position, size, and stacking 
order of SUBWINDOW_1 


RECORD /XS$WINDOW_CHANGES/ XWC 


WCHG MASK = X$M CW_X .OR. XSM_CW_Y .OR. XSM_CW_WIDTH .OR. 


1 X$M_CW HEIGHT .OR. X$M_CW SIBLING .OR. X$M_CW_STACK MODE 
XWC.X$L_WCHG X = 200 
XWC.X$L_WCHG Y = 350 


XWC.X$SL_WCHG WIDTH = 200 


XWC.X$L_WCHG HEIGHT = 50 


. XWC.XSL_WCHG_ SIBLING = SUBWINDOW_2 


XWC.X$L_WCHG STACK_MODE = X$C_ABOVE 


CALL XSCONFIGURE_WINDOW(DPY, SUBWINDOW_1, WCHG_MASK, XWC) 


@ Specify the members of the window changes data structure that 
have assigned values. Create a mask by performing a bitwise OR 
operation on relevant flags that indicate which members of WINDOW 
CHANGES the client will define. 


@ Assign values to relevant members of the window changes data 
structure. Because the client identifies a sibling (SUBWINDOW_ 
1), it must also choose a mode for stacking operations. 


© The call to reconfigure SUBWINDOW_1. The CONFIGURE WINDOW 
routine call has the following format: 


XSCONFIGURE_WINDOW (display, window_id, change_mask, values) 


Figure 3-12 illustrates how the windows look after being reconfigured. 
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Figure 3-12 Reconfigured Window 


SUBWINDOW_1 SUBWINDOW_2 
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Table 3-14 lists routines to change individual window characteristics. 


Table 3-14 Window Configuration Routines 


Routine Description 

MOVE WINDOW Moves a window without changing its size. 

RESIZE WINDOW Changes the size of a window without moving it. The 
upper left window coordinate does not change after 
resizing. 

MOVE RESIZE WINDOW Moves and changes the size of a window. 

SET WINDOW BORDER Changes the border width of a window. 

WIDTH 


3.6.2. Effects of Reconfiguring Windows 
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It is important to know how reconfiguring windows affects graphics and 
text drawn in them by the client. (See Chapter 6 for a description of 
working with graphics and Chapter 8 for a description of writing text.) 
When a client resizes a window, window contents are either moved or lost, 
depending on the bit gravity of the window. Bit gravity indicates that a 
designated region of the window should be relocated when the window is 
resized. Resizing also causes the server to resize children of the changed 
window. 


To control how the server moves children when a parent is resized, set the 
window gravity attribute. Table 3-15 lists choices for retaining window 
contents and controlling how the server relocates children. 


Table 3-15 Gravity Definitions 


Movement of Window Contents and 
Constant Name Subwindows 


x$c_forget_gravity The server always discards window contents and 
tiles the window with its selected background. If 
the client has not specified a background, existing 
screen contents remain the same. 


x$c_north_west_gravity Not moved. 


x$c_north_gravity Moved to the right half the window width. 

x$c_north_east_gravity Moved to the right the distance of the window 
width. 

x$c_west_gravity Moved down haif the window height. 

x$c_center_gravity Moved to the right half the window width and down 
half the window height. 

x$c_east_gravity Moved to the right the distance of the window width 
and down half the window height. 

x$c_south_west_gravity Moved down the distance of the window height. 


(continued on next page) 
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Table 3-15 (Cont.) Gravity Definitions 


Constant Name 


x$c_south_gravity 
x$c_south_east |_ gravity 


x$c_static_gravity 


x$c_unmap_gravity 


Movement of Window Contents and 
Subwindows 


Moved ito the right half the window width and down 
the distance of the window height. 


Moved to the right the distance of the window width 
and down the distance of the window height. 


Contents or origin is not moved relative to the 
origin of the root window. Static gravity only takes 
effect with a change in window width or height. 


Window should not be moved; the child should be 
unmapped when the parent is resized. 


Figure 3—13 illustrates how the server moves the contents of a 
reconfigured window when the bit gravity is set to the constant 


x$c_east_gravity. 


Figure 3—14 illustrates how the server moves a child window if its parent 
is resized and its window gravity is set to the constant x$c_northwest_ 


gravity. 


Figure 3-13 East Bit Gravity 


Original Window 











Resized Window 


h/2 
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Figure 3-14 Northwest Window Gravity 


Original Parent and Child Windows 


—— 





Child Parent 


Resized Parent Window | 
a 2 
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ZK-0073A-GE 


3.6.3. Changing Stacking Order 


Xlib provides routines that alter the window stacking order in the 
following ways: 


¢ A specified window moves to either the top or the bottom of the stack. 
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¢ The lowest mapped child obscured by a sibling moves to the top of the 
stack. 


¢ The highest mapped child that obscures a sibling moves to the bottom 
of the stack. 


Use the RAISE WINDOW and LOWER WINDOW routines to move a 
specified window to either the top or the bottom of the stack, respectively. 


To raise the lowest mapped child of an obscured window to the top of the 
stack, call CIRCULATE SUBWINDOWS UP. To lower the highest mapped 
child that obscures another child, call CIRCULATE SUBWINDOWS 
DOWN. The CIRCULATE SUBWINDOWS routine enables the client to 
perform these operations by specifying either the constant x$c_raise_ 
lowest or the constant x$c_lower_highest. 

To change the order of the window stack, use RESTACK WINDOW, which 
changes the window stack to a specified order. Reordered windows must 
have a common parent. If the first window the client specifies has other 
unspecified siblings, its order relative to those siblings remains unchanged. 


3.6.4 Changing Window Attributes | 
Xlib provides routines that enable clients to change the following: 
° Default contents of an input-output window 
¢ Border of an input-output window 
¢ Treatment of the window when it or its relative is obscured 
¢. Treatment of the window when it or its relative is moved 


e Information the window receives about operations associated with 
— other windows 


¢ Color 


e. Cursor 


Section 3.2.2 includes descriptions of window attributes and their 
relationship to the set window attributes data structure. 


This section describes how to change any attribute using the CHANGE 
WINDOW ATTRIBUTES routine. In addition to CHANGE WINDOW 
ATTRIBUTES, Xlib includes routines that enable clients to change 
background and border attributes. Table 3-16 lists these routines and 
their functions. 
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Table 3-16 Routines for Changing Window Attributes 


Routine Description 

SET WINDOW BACKGROUND Sets the background pixel 

SET WINDOW BACKGROUND PIXMAP Sets the background pixmap 

SET WINDOW BORDER Sets the window border to a specified 
pixel 

SET WINDOW BORDER PIXMAP Sets the window border to a specified 
pixmap 


To change any window attribute, use CHANGE WINDOW ATTRIBUTES 
as follows: 


e Assign a value to the relevant member of a set window attributes data 
structure. 


¢ Indicate the attribute to change by specifying the appropriate flag 
and passing it to the CHANGE WINDOW ATTRIBUTES value_mask 
argument. To define more than one attribute, indicate the attributes 
by doing a bitwise OR on the appropriate flags. 


See Table 3-3 for symbols Xlib assigns to each member to facilitate 
referring to the attributes. 


Example 3-6 illustrates using CHANGE WINDOW ATTRIBUTES to 
redefine the characteristics of a window. 


Example 3-6 Changing Window Attributes 


RECORD /X$SET_WIN_ATTRIBUTES/ XSWDA 


ATTR_MASK = X$M_CW_BORDER PIXEL .OR. X$M_CW_BACK_ PIXEL 


XSWDA.X$L_SWDA_BACKGROUND_ PIXEL = X$BLACK_PIXEL_OF_SCREEN (SCREEN) 
XSWDA.X$L_SWDA_BORDER_PIXEL = XSWHITE_ PIXEL OF SCREEN (SCREEN) 


CALL X$CHANGE WINDOW ATTRIBUTES (DPY, WINDOW, ATTR_MASK, XSWA) 


@ Assign new values to a set window attributes data structure. 


@ Call CHANGE WINDOW ATTRIBUTES to change the window 
attributes. The CHANGE WINDOWS attributes routine has the 
following format: 


X$CHANGE WINDOW ATTRIBUTES (display, window_id, 
attributes mask, attributes) 


Specify the attributes to change with a bitwise inclusive OR of the 
relevant symbols listed in Table 3-3. The values argument passes the 
address of a set window attributes data structure. 
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Table 3-17 lists changes in attributes and their effects. 


Table 3-17 Effects of Window Attribute Changes 


Attribute Changed 


Background 


Border 


Bit and window gravity 
Backing store 

Backing planes 
Backing pixels 

Save under 


Event mask 

Do not propagate mask 
Color map 

Cursor 


3.7 Getting Information About Windows 


Effects 


Window contents are unchanged. 


if the window is a root window, specifying the constant 
x$c_none or x$c_parent_relative restores the default 
background pixmap. 


The server does not repaint the background 
automatically. 


Setting the border causes the border to be repainted. 


If a background change causes a change in the 
border tile origin, the server repaints the border. 


Specifying the constant x$c_copy_from_parent on a 
root window restores the default border pixmap. 


A change in window gravity has no effect until the 
window is resized. 


In this release of the DECwindows server, backing 
store is not supported. 


in this release of the DECwindows server, backing 
planes is not supported. 


In this release of the DECwindows server, backing 
pixels is not supported. 


If the window is mapped, changing the value of save 
under may have no immediate effect. 


See Chapter 9. 
See Chapter 9. 
See Chapter 5. 


Specifying the constant x$c_none on a root window 
restores the default cursor. 


Using Xlib information routines, clients can get information about the 
parent, children, and number of children in a window tree; window 
geometry; the root window in which the pointer is currently visible; and 


window attributes. 


Table 3-18 lists and describes Xlib routines that return information about 


windows. 
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Table 3-18 Window Information Routines 


Routine Description 
QUERY TREE Returns information about the window tree 
GET GEOMETRY Returns information about the root window 


identifier, coordinates, width and height, border 
width, and depth 


QUERY POINTER Returns the root window the pointer is 
currently on and the pointer coordinates 
relative to the root window origin 


GET WINDOW ATTRIBUTES Returns information from the window attributes 
data structure 


To get information about window attributes, use the GET WINDOW 
ATTRIBUTES routine. The client receives requested information in the 
window attributes data structure. Figure 3-15 illustrates the window 
attributes data structure. Table 3-19 describes the members of the data 
structure. 


Figure 3-15 Window Attributes Data Structure 
























; 
2 
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x$i_wdat_class 32 
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x$l_wdat_backing_planes 48 
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Figure 3-15 (Cont.) Window Attributes Data Structure 
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Table 3-19 Window Attributes D 


ta Structure Members 





Member Name 


X$L_WDAT_X 

XSL WOAT_Y 
X$L_WDAT_WIDTH 
X$L_WDAT_HEIGHT 


X$L_WDAT_BORDER_WIDTH 
X$L_WDAT_DEPTH 
X$L_WDAT_VISUAL 


X$L_WDAT_ROOT 
X$L_WDAT_CLASS 


X$L_WDAT_BIT_GRAVITY 
X$L_WDAT_WIN_GRAVITY 


X$L_WDAT_BACKING_STORE 


Contents 
Specifies the x-coordinate of the upper left corner of the window 
relative to its parent. 


Specifies the y-coordinate of the upper left corner of the window 
relative to its parent. . 


Specifies the width of the window, excluding the window border, in 
pixels. 


Specifies the height of the window, excluding the window border, in 
pixels. 


Specifies the width of the window border in pixels. 
Specifies the bits per pixel of the window. 


The visual data structure associated with the window. The visual 
data structure specifies how displays should treat color resources. 
For more information, see Section 3.5.1. 


Identifies the screen with which the window is associated. 
Specifies whether the window accepts input and output, or input 
only. 

Specifies how pixels should be moved when the window is resized. 


Specifies how the window should be repositioned when its parent is 
resized. 


Indicates whether or not the server should maintain a record 
of portions of a window that are obscured when the window is 
mapped. In this release, clients must maintain window contents. 
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Table 3-19 (Cont.) Window Attributes Data Structure Members 


Member Name 


X$L_WDAT_BACKING_PLANES 


X$L_WDAT_BACKING_PIXEL 


X$L_WDAT_SAVE_UNDER 


X$L_WDAT_COLORMAP 


X$L_WDAT_MAP_INSTALLED 


X$L_WDAT_MAP_STATE 


X$L_WDAT_ALL_EVENTS_MASK 


X$L_WDAT_YOUR_EVENT_MASK 


X$L_WDAT_DO_NOT_PROPAGATE_MASK 


X$L_WDAT_OVERRIDE_REDIRECT 


X$L_WDAT_SCREEN 


Contents 


Indicates (with bits set to 1) which bit planes of the window hold 
dynamic data that must be preserved in backing stores and during 
save under operations. In this release, clients must maintain their 
own data. 


Defines what values to use in planes not specified by X$L_WDAT_ 
BACKING_PLANES. In this release, clients must maintain their own 
values. 


Setting this member to true informs the server that the client would 
like the contents of the screen saved when the window obscures 
them. Saving the contents of obscured portions of the screen is not 
guaranteed. 


Specifies the color map, if any, that best reflects the colors of the 
window. The color map must have the same visual type as the 
window. If it does not, an error occurs. For more information about 
color maps, see Chapter 5. 


If set to true, indicates that the color map is currently installed and 
the window is being displayed in its correct colors. 


Indicates whether the window is mapped and viewable. Clients can 
specify the following constants: 


Constant Name Description 
x$c_is_unmapped Indicates that the window is not mapped 
x$c_is_unviewable Indicates that the window is mapped, but 


that one of its ancestors is unmapped, 
causing the window to be unviewable 


x$c_is_viewable Indicates that the window is mapped and 
viewable 


Indicates the set of events in which all applications have an 
interest. X$L_WDAT_ALL_EVENTS_MASK is the inclusive OR of 
all event masks set for the window. For more information about 
event masks, see Chapter 9. 


Indicates the events about which the querying client is interested in 
receiving notice. 


Defines which events should not be propagated to a window’s 
ancestors when no application has the event type selected in the 
window. 


Specifies whether requests to map and configure the window 
should override a request by another client to redirect those calls 
(see Chapter 9). Typically, this mask, which informs the window 
manager not to tamper with the window, should be used only on 
subwindows such as menus. 


Specifies the screen on which the window is mapped. 


4. Defining Graphics Characteristics. SSS 


After opening a display and creating a window, clients can draw lines 
and shapes, create cursors, and draw text. Creating a graphics object is 

a two-step process. Clients first define the characteristics of the graphics 
object and then create it. For example, before creating a line, a client first 
defines line width and style. After defining the characteristics, the client 
creates the line with the specified width and style. 


This chapter describes how to define the graphics characteristics prior to 
creating them, including the following topics: 


¢ The graphics context—A description of the graphics characteristics a 
client can define and the GC values data structure used to define them 


¢ Defining graphics characteristics—How to define graphics 
' characteristics using the CREATE GC routine 


¢ Copying, changing, and freeing attributes—How to copy, change, and 
undefine graphics characteristics 


¢ Defining graphics characteristics efficiently—How to work efficiently 
with several sets of graphics characteristics 


Chapter 6 describes how to create graphics objects. Chapter 8 describes 
how to work with text. 





4.1 The Graphics Context 


The characteristics of a graphics object make up its graphics context. As 
with window characteristics, Xlib provides a data structure and routine 

to enable clients to define multiple graphics characteristics easily. By 
setting values in the GC values data structure and calling the CREATE 
GC routine, clients can define all characteristics relevant to a graphics 
object. 


Xlib also provides routines that enable clients to define individual or — 
functional groups of graphics characteristics. 


Xlib always records the defined values in a GC data structure, which is 
reserved for the use of Xlib and the server only. This occurs when clients 
define graphic characteristics using either the CREATE GC routine or one 
of the individual routines. Table 4—1 lists the default values of the GC 
data structure. 
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Table 4-1 GC Data Structure Default Values 


Member 


Function 

Plane mask 
Foreground 
Background 

Line width 

Line style 

Cap style 

Join style 

Fill style 

Fill rule 

Are mode 

Tile 

Stipple 

Tile or stipple x origin 
Tile or stipple y origin 
Font 

Subwindow mode 
Graphics exposures 
Clip x origin 

Clip y origin 

Clip mask 

Dash offset 

Dashes 


Default Value 


x$c_gx_copy 

All ones 

0 

1 

0 

Solid 

Butt 

Miter 

Solid 

Even odd 

Pie slice . 
Pixmap of unspecified size filled with foreground pixel 
Pixmap of unspecified size filled with ones 
0 

0 

Varies with implementation 

Clip by children 

True 

0 

0 

None 

0 

4 (the list [4,4]) 


4.2 _ Defining Multiple Graphics Characteristics in One Call 


Xlib enables clients to define multiple characteristics of a graphics object 
in one call. To define multiple characteristics, use the CREATE GC routine 
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as follows: 


e Assign values to the relevant members of the GC values data 


structure. 


¢ Indicate the attributes to define by specifying the appropriate flag and 
passing the flag to the value_mask argument of the routine. To define 
more than one attribute, do a bitwise OR on the appropriate attribute 


flags. 
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- Figure 4-1 illustrates the GC values data structure. 
Figure 4-1 GC Values Data Structure 


x$l_gevl_function 
x$l_gevl_plane_mask 
x$l_gevl_foreground 
x$l_gevl_background 
x$l_gevl_line_width 
x$l_gcevi_line_style 
x$l_gevl_cap_style 
x$l_gcevi_join_style 
_ x$l_gevi_fill_style — 
| x$l_gevi_fill_rule 
x$l_gevl_arc_mode 
x$l_gevi_tile 
x$l_gevl_stipple 
x$l_gevl_ts_x_origin 
x$l_gevi_ts_y_origin 


x$l_gcvi_font 


x$I_govl_subwindow_mode 


x$l_gcvl_graphics_exposures 
x$l |__gevi_clip_x_origin 
x$l_gcvi_clip_y_origin 


x$l_gevi_clip_mask 


| x$l_gcevi_dash_offset 





x$b_gevl_dashes 
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Table 4—2 describes the members of the data structure. 


Table 4-2 GC Values Data Structure Members © 


Member Name 


X$L_GCVL_FUNCTION 


X$L_GCVL_PLANE_MASK 


X$L_GCVL_FOREGROUND 
X$L_GCVL_BACKGROUND 


Contents 


Defines how the server computes pixel values when the client updates a 
section of the screen. The following lists available functions: 


Constant Name Description 
X$C_GX_CLEAR 0 

x$C_GX_AND src AND dst 
X$C_GX_AND_REVERSE src AND NOT dst 
X$C_GX_COPY src 
X$C_GX_AND_INVERTED (NOT src) AND dst 
X$C_GX_NOOP dst 

X$C_GX_XOR src XOR dst 
X$C_GX_OR sre OR dst 
X$C_GX_NOR (NOT src) AND NOT dst 
X$C_GX_EQUIV (NOT src) XOR dst 
X$C_GX_INVERT NOT dst. 
X$C_GX_OR_REVERSE src OR NOT dst 
X$C_GX_COPY_INVERTED NOT src 
X$C_GX_OR_INVERTED (NOT src) OR dst 


X$C_GX_NAND 
X$C_GX_SET 


(NOT src) OR NOT dst 
1 





The screen the client is updating is the destination (dst). The graphics 
context the client uses to update the screen is the source (src). X$L_ 
GCVL_FUNCTION specifies how the server computes new destination 
bits from the source (src) and the old bits of the destination (dst). 


The most common logical function is the default specified by the constant 
x$c_gx_copy, which only uses relevant values in the specified GC values 
data structure to update the screen. 


Specifies the planes on which the server performs the bitwise 
computation of pixels, defined by X$L_GCVL_FUNCTION. 


Because a monochrome display has only one plane, the plane mask 
value is given in the least significant bit of the longword. As planes are 
added to the display hardware, they are defined in the more significant 
bits of the mask. The display routine ALL PLANES specifies that all 
planes of the display are referred to simultaneously. 


The server does not perform range checking on the plane mask. It 
truncates values to the appropriate number of bits. 


Specifies an index to a color map entry for foreground color. 
Specifies an index to a color map entry for background color. 
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Table 4—2 (Cont.) GC Values Data Structure Members 


Member Name 


X$L_GCVL_LINE_WIDTH 


Contents 


Defines the width of a line in pixels. 


The server draws a line with a width of one or more pixels centered 

on the path described in the graphics request and contained within a 
bounding box. Unless otherwise specified by the join or cap style, the 
bounding box of a line with endpoints [ #1, y1], [ 22, y2] and width w > 0 
is a rectangle with vertices at the following real coordinates: 


[xl-w*sn/2, yltw*cs/2], [xl+w*sn/2, yl-w*cs/2] 
[x2-w*sn/2, y2+tw*cs/2], [x2+w*sn/2, y2-w*cs/2] 


In this example, sn is the sine of the angle of the line. The symbol cs is 
the cosine of the angle of the line. A pixel is part of the line and is drawn 
if the center of the pixel is fully inside the bounding box. If the center 

of the pixel is exactly on the bounding box, the pixel is part of the line if 
and only if the interior is immediately to its right (x increasing direction). 
Pixels with centers on a horizontal edge are a special case and are part 
of the line if and only if the interior is immediately below the bounding box 
(y increasing direction). See Figure 4-2. 


Lines with zero line width are one pixel wide. The server draws them 
using an unspecified, device-dependent algorithm that imposes the 
following two constraints: 


* — |f the server draws the line unclipped from [ x1, y1] to [ 22, y2], and 
if the server draws a second line from [ 21+ dz, y1 + dy] to [ 22+dz, 
y2 + dy], then point [ z, y] is touched by drawing the first line if and 
only if the point [ z + dz, y + dy] is touched by drawing the second 
line. 

* The effective set of points that compose a line cannot be affected by 
clipping. That is, a point is touched in a clipped line if and only if the 
point lies inside the clipping region and if the point would be touched 
by the line when drawn unclipped. 


A line more than one pixel wide drawn from [ 21, y1] to [ 22, y2] always 
draws the same pixels as a line of the same width drawn from [ 22, y2] to 
[ 21, y1], excluding cap and join styles. 


In general, drawing a line whose line width is zero is substantially faster 
than drawing a line whose line width is one or more. However, because 
the drawing algorithms for thin lines is different than those for wide lines, 
thin lines may not look as good when mixed with wide lines. If clients 
want precise and uniform results across all displays, they should always 
use a line width of one or more. Note, however, that specifying a line 
width of greater than zero decreases performance substantially. 





(continued on next page) 
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Table 4-2 (Cont.) GC Values Data Structure Members 


Member Name Contents 

X$L_GCVL_LINE_STYLE Defines which sections of the line the server draws. The following lists 
available line styles and the constants that specify them: 
Constant Name Description | 
x$c_line_solid The full path of the line is drawn. 
x$c_line_double_dash The full path of the line is drawn, but the 


even dashes are filled differently than the 
odd dashes, with cap butt style used where 
even and odd dashes meet. 

x$c_line_off_on_dash Only the even dashes are drawn. The 
X$L_CAP_STYLE member applies to all 
internal ends of dashes. Specifying the 
constant, x$c_cap_not_last, is equivalent to 
specifying x$c_cap_butt. 


Figure 4—3 illustrates the styles. 


X$L_GCVL_CAP_STYLE Defines how the server draws the endpoints of a path. The following lists 
available cap styles and the constants that specify them: 





Constant Name Description 


x$c_cap_butt Square at the endpoint (perpendicular to 
the slope of the line) with no projection 
beyond the endpoint 


x$c_cap_not_last Equivalent to specifying x$c_cap_bultt, 
except that the final endpoint is not drawn if 
the line width is zero or one 


x$c_cap_round A circular arc with the diameter equal to 
the line width, centered on the endpoint 
(equivalent to specifying x$c_cap_buitt for a 
line width of zero or one) 


x$c_cap_projecting Square at the end, but the path continues 
beyond the endpoint for a distance equal 
to half the width of the line (equivalent to 
specifying x$c_cap_butt for a line width of 
zero or one) 





Figure 4-4 illustrates the butt, round, and projecting cap styles. 
Figure 4—5 illustrates the style specified by the constant x$c_cap_ 
not_last. 


(continued on next page) 
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Table 4—2 (Cont.) GC Values Data Structure Members 


Member Name 


Contents 





X$L_GCVL_JOIN_STYLE 


If a line has coincident endpoints ( z1 = 22, y1 = y2), the cap style is 
applied to both endpoints with the following results: 


Line 
Constant Name Width 
x$c_cap_not_last Thin 
x$c_cap_butt Thin 
x$c_cap_butt Wide 
x$c_cap_round Thin 
x$c_cap_round Wide 


x$c_cap_projecting Thin 


x$c_cap_projecting Wide 


Description 


Device dependent, but the desired 
effect is that nothing is drawn. 


Device dependent, but the desired 
effect is that a single pixel is drawn. 


Nothing is drawn. 


Device dependent, but the desired 
effect is that a single pixel is drawn. 


The closed path is a circle, centered 
at the endpoint, with the diameter 
equal to the line width. 


Device dependent, but the desired 
effect is that a single pixel is drawn. 


The closed path is a square, aligned 
with the coordinate axes, centered 
at the endpoint with sides equal to 
the line width. 


Defines how the server draws corners for wide lines. Available join styles 
and the constants that specify them are as follows: 


Constant Name Description 

x$c_join_miter The outer edges of the two lines extend to meet 
at an angle. 

x$c_join_round A circular arc with diameter equal to the line 
width, centered at the join point. 

x$c_join_bevel Cap buit endpoint style, with the triangular notch 
filled. 


Figure 4—6 illustrates the styles. 


For a line with coincident endpoints ( #1 = 22, yl = y2), when the join 
style is applied at one or both endpoints, the effect is as if the line were 
removed from the overall path. However, if the total path consists of (or 
is reduced to) a single point joined with itself, the effect is the same as if 
the X$L_GCVL_CAP_STYLE were applied to both endpoints. 


(continued on next page) 
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Table 4—2 (Cont.) GC Values Data Structure Members 


Member Name 


X$L_GCVL_FILL_STYLE 


4-8 


Contents 


Specifies the contents of the source for line, text, and fill operations. The 
following lists available fill styles for text and fill requests (DRAW TEXT, 
DRAW TEXT 16, FILL RECTANGLE, FILL POLYGON, FILL ARC). It also 
lists available styles applicable to solid lines and even dashes resulting 
from line requests (LINE, SEGMENTS, RECTANGLE, ARC): 


Constant Name 


x$c_fill_solid 
x$c_fill_tiled 
x$c_fill_opaque_stippled 


x$c_fill_stippled 


Description 


Foreground 

Tile 

A tile with the same width and height as 
stipple but with background everywhere 


stipple has a zero and with foreground 
everywhere stipple has a one 


Foreground masked by stipple 


The following lists available styles applicable to odd dashes resulting 


from line requests: 
Constant Name. 
x$c_fill_solid 
x$c_fill_tiled 
x$c_fill_opaque_stippled 


x$c_fill_stippled 


Description 


Background 
Tile 


A tile with the same width and height as 
stipple but with background everywhere 
stipple has a zero and with foreground 
everywhere stipple has a one 


Background masked by stipple 


(continued on next page) 
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Table 4—2 (Cont.) GC Values Data Structure Members 


Member Name 


X$L_GCVL_FILL_RULE 


X$L_GCVL_ARC_MODE 


X$L_GCVL_TILE 


Contents 


Defines what pixels the server draws along a path when a polygon is 
filled (see Section 6.5.2). The two available choices are x$c_even_odd_ 
rule and x$c_winding_rule. The x$c_even_odd_rule constant defines 

a point to be inside a polygon if an infinite ray with the point as origin 
crosses the path an odd number of times. If the point meets these 
conditions, the server draws a corresponding pixel. 


The x$c_winding_rule constant defines a point to be inside the polygon 

if an infinite ray with the pixel as origin crosses an unequal number of 
clockwise-directed and counterclockwise-directed path segments. A 
clockwise-directed path segment is one that crosses the ray from left to 
right as observed from the pixel. A counterclockwise-directed segment 

is one that crosses the ray from right to left as observed from that point. 
When a directed line segment coincides with a ray, choose a different ray 
that is not coincident with a segment. If the point meets these conditions, 
the server draws a corresponding pixel. 


For both even odd rule and winding rule, a point is infinitely small, and 
the path is an infinitely thin line. A pixel is inside the polygon if the center 
point of the pixel is inside, and the center point is not on the boundary. 

If the center point is on the boundary, the pixel is inside if and only if 
the polygon interior is immediately to its right (x increasing direction). 
Pixels with centers along a horizontal edge are a special case and are 
inside if and only if the polygon interior is immediately below (y increasing 
direction). , 


Figure 4—7 illustrates fill rules. Figure 4—8 illustrates rules for filling a 
pixel when it falls on a boundary. 


Controls how the server fills an arc. The available choices are specified 
by the constants x$c_arc_pie_slice and x$c_arc_chord. Figure 4-9 
illustrates the two modes. 


Specifies the pixmap the server uses for tiling operations. The pixmap 
must have the same root and depth as the graphics context, or an error 
occurs. Clients can use any size pixmap for tiling, although some sizes 
produce a faster response than others. To determine the optimum size, 
use the QUERY BEST SIZE routine. 


Storing a pixmap in a graphics context might or might not result in a copy 
being made. If the pixmap is later used as the destination for a graphics 
request, the change might or might not be reflected in the graphics 
context. If the pixmap is used simultaneously in a graphics request both 
as a destination and as a tile, the results are not defined. 





(continued on next page) 
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Table 4-2 (Cont.) GC Values Data Structure Members 


Member Name 


X$L_GCVL_STIPPLE 


X$L_GCVL_TS_X_ORIGIN 
X$L_GCVL_TS_Y_ORIGIN 


X$L_GCVL_FONT 
X$L_GCVL_SUBWINDOW_MODE 


X$L_GCVL_GRAPHIC_EXPOSURES 
X$L_GCVL_CLIP_X_ORIGIN 
X$L_GCVL_CLIP_Y_ORIGIN 


X$L_GCVL_CLIP_MASK 


X$L_GCVL_DASH_OFFSET 


X$B_GCVL_DASHES 


Contents 


Specifies the pixmap the server uses for stipple operations. The pixmap 
must have the same root as the graphics context and a depth of one, 

or an error occurs. For stipple operations where the fill style is specified 
as x$c_fill_stippled but not x$c_fill_opaque_stipple constant, the stipple 
pattern is tiled in a single plane and acts as an additional clip mask. 
Perform a bitwise AND operation with the clip mask. Clients can use any 
size pixmap for stipple operations, although some sizes produce a faster 
response than others. To determine the optimum size, use the QUERY 
BEST SIZE routine. 


Defines the origin for tiling and stipple operations. Origins are relative 
to the origin of whatever window or pixmap is specified in the graphics 
request. 


Defines the origin for tiling and stipple operations. Origins are relative 
to the origin of whatever window or pixmap is specified in the graphics 
request. 


Specifies the font that the server uses for text operations. 


Specifies whether or not inferior windows clip superior windows. The 
constant x$c_clip_by_ children specifies that all viewable input-output 
children clip both source and destination windows. The constant x$c_ 
include_inferiors specifies that inferiors clip neither source nor destination 
windows. This results in drawing through subwindow boundaries. The 
semantics of using the constant on a window with a depth of one and 
with mapped inferiors of differing depth is undefined by the core protocol. 


‘Specifies whether or not the server informs the client when the contents 


of a window region are lost. 


Defines the x-coordinate of the clip origin. The clip origin specifies the 
point within the clip region that is aligned with the drawable origin. | 


Defines the y-coordinate of the clip origin. The clip origin specifies the 
point within the clip region that is aligned with the drawable origin. 


Identifies the pixmap the server uses to restrict write operations to the 
destination drawable. The pixmap must have a depth of one and have 
the same root as the graphics context. The clip mask clips only the 
destination drawable, not the source drawable. Where a value of one 
appears in the mask, the corresponding pixel in the destination drawable 
is drawn; where a value of zero occurs, no pixel is drawn. Any pixel 
within the destination drawable that is not represented within the clip 
mask pixmap is not drawn. When a client specifies the value of clip mask 
as x$c_none, the server draws all pixels. 


Specifies the pixel within the dash length sequence, defined by X$B_ 
GCVL_DASHES, to start drawing a dashed line. For example, a dash 
offset of zero starts a dashed line as the beginning of the dash line 
sequence. A dash offset of five starts the line at the fifth pixel of the line 
sequence. 


Specifies the length, in number of pixels, of each dash. The value of this 
member must be nonzero or an error occurs. 
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Figure 4-2 Bounding Box 
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Figure 4—3 Line Styles 
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Figure 4—4 Butt, Round, and Projecting Cap Styles 
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Figure 4-5 Cap Not Last Style 
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Figure 4—6 Join Styles 
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Figure 4-7 Fill Rules 
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Figure 4-8 Pixel Boundary Cases 


Pixels are 
inside 


Polygon 
C 


Pixels are 
Outside 
Polygon 


ZK-0075A-GE 


Figure 4-9 Styles for Filling Arcs . 
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Figure 4-10 Dashed Line Offset 
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Xlib assigns a flag for each member of the GC values data structure to 
facilitate referring to members (Table 4-3). 


Table 4-3 GC Values Data Structure Flags 


Flag Name 


x$m _ge_function 
x$m_ge_plane_mask 
x$m_gc_foreground 
x$m_gc_background 
x$m_gc_line_width 
x$m_gce_line_style 
x$m_gce_cap_style 
x$m_gc_join_style 
x$m_gc_fill_style 
x$m_gc_fill_rule 
x$m_gc_tile 
x$m_gc_stipple 
x$m_gc_tile_stip_x_origin 
x$m _gc_tile_stip_y origin 
x$m_gc_font 
x$m_gc_subwindow_mode 
x$m_gc_graphics_exposures 
x$m_gc_clip_x_origin 


GC Values Member 


X$L_GCVL_FUNCTION 
X$L_GCVL_PLANE_MASK 
X$L_GCVL_FOREGROUND 
X$L_GCVL_BACKGROUND 
X$L_GCVL_LINE_WIDTH 
X$L_GCVL_LINE_STYLE 
X$L_GCVL_CAP_STYLE 
X$L_GCVL_JOIN_STYLE 
X$L_GCVL_FILL_STYLE 
X$L_GCVL_FILL_RULE 
X$L_GCVL_TILE 
X$L_GCVL_STIPPLE 
X$L_GCVL_TS_X_ORIGIN 
X$L_GCVL_TS_Y_ORIGIN 
X$L_GCVL_FONT 
X$L_GCVL_SUBWINDOW_MODE 
X$L_GCVL_GRAPHICS_EXPOSURES 
X$L_GCVL_CLIP_X_ORIGIN 


(continued on next page) 
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Table 4-3 (Cont.) GC Values Data Structure Flags 


Flag Name GC Values Member 
x$m_gc_clip_y_origin X$L_GCVL_CLIP_Y_ORIGIN 
x$m_ge_clip_mask X$L_GCVL_CLIP_MASK 
x$m_gc_dash_offset X$L_GCVL_DASH_OFFSET 
x$m_gc_dash_list X$B_GCVL_DASHES 


x$m_gc_arc_mode . X$L_GCVL_ARC_MODE 


Example 4—1 illustrates how a client can define graphics context values 
using the CREATE GC routine. Figure 4—11 shows the resulting output. 


Example 4—1 Defining Graphics Characteristics Using the CREATE GC Routine 


INTEGER*4 GC 
INTEGER*4 GC_MASK 
RECORD /X$GC_VALUES/ XGCVL 


PARAMETER X1 = 100, Y1 = 
= 550, Y2 = 550 


1 X2 

Cc 

Cc Create the graphics context 

Cc 

1] GC_MASK = X$M_GC_FOREGROUND .OR. X$M_ GC_BACKGROUND .OR. 
1 XS$M_GC_ LINE _| WIDTH .OR. X$M_GC_ LINE _ “STYLE .OR. XSM_GC_DASH_OFFSET 
1 -OR. X$M_| GC: _ DASH_LIST 

2) XGCVL.X$L_GCVL_FOREGROUND = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 3) 
XGCVL.X$L_GCVL_BACKGROUND = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 4) 
XGCVL.X$L_GCVL_LINE_ WIDTH = 4 
XGCVL.X$L_GCVL_LINE_ STYLE = X$C_LINE_DOUBLE_DASH 
XGCVL.X$L_GCVL_DASH_OFFSET = 0 
XGCVL.X$B_GCVL_DASHES = 25 

C3 GC = X$CREATE_GC(DPY, WINDOW, GC_MASK, XGCVL) 

4) CALL X$DRAW_LINE(DPY, WINDOW, GC, Xl, Y1, X2, Y2) 


@ Specify the members of the GC values data structure that will have 
assigned values. 


@ Specify the foreground, background, line width, line ees dash onees, 
and dashes for line drawing. 


The dashed line is four pixels wide. A dash offset value of zero starts 
dashes at the beginning of the line. The dashes value specifies that 
dashes be 25 pixels long. 
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© The CREATE GC routine loads values into a GC data structure. The 
CREATE GC routine has the following format: 


gc_id = X$CREATE GC (display, drawable _id, gc_mask, 
values struc) 


@ See Chapter 6 for information about drawing lines. 


Figure 4-11 Dashed Line 


Dashed Line 


| Click MB1 to draw a dashed line. 
Click MB3 to exit. 
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4.3 | Defining Individual Graphics Characteristics 


- Xlib offers routines that enable clients to define individual or functional 

_ groups of graphics characteristics. Table 4—4 lists and briefly describes 
these routines. For more information about the components, see 
Section 4.1. 
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Table 4-4 Routines That Define Individual or Functional Groups of 
Graphics Characteristics 


Routine 


Description 


Foreground, Background, Plane Mask, and Function Routines 


SET STATE 


SET FOREGROUND 
SET BACKGROUND 
SET PLANE MASK 
SET FUNCTION 


Line Attribute Routines 


SET LINE ATTRIBUTES 


SET LINE DASHES 


Fill Style and Rule Routines . 


SET FILL STYLE 


SET FILL RULE 


Fill Tile and Stipple Routines 
QUERY BEST SIZE 


QUERY BEST STIPPLE 
QUERY BEST TILE 


SET STIPPLE 
SET TILE 
SET TS ORIGIN | 


Font Routine 


SET FONT 


Sets the foreground, background, plane mask, 
and function 


Sets the foreground 
Sets the background 
Sets the plane mask 
Sets the function 


Sets line width, line style, cap style, and join 
style 


Sets the dash offset and dash list of a line 


Sets fill style to solid, tiled, stippled, or opaque 
stippled 


Sets fill rule to either even and odd or winding 
rule 


Queries the server for the size closest to the 
one specified 


Queries the server for the closest stipple 
shape to the one specified 


Queries the server for the closest tile shape to 


the one specified 


Sets the stipple pixmap 
Sets the tile pixmap 
Sets the tile or stipple origin 


Sets the current font 
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Table 4—4 (Cont.) Routines That Define Individual or Functional Groups 
of Graphics Characteristics 


Routine Description 


Clip Region Routines 


SET CLIP MASK Sets the mask for bitmap clipping 
SET CLIP ORIGIN Sets the origin for clipping 
SET CLIP RECTANGLES Changes the clip mask from its current value 


to the specified rectangles 


Arc, Subwindow, and Exposure Routines 


SET ARC MODE Sets the arc mode to either chord or pie slice 


SET SUBWINDOW MODE Sets the subwindow mode to either clip by 
children or include inferiors 
SET GRAPHICS EXPOSURES Specifies whether exposure events are created 


when calling COPY AREA or COPY PLANE 


Example 4—2 illustrates using individual routines to set background, 
foreground, and line attributes. Figure 4-12 illustrates the resulting 
output. 


Example 4-2 Using Individual Routines to Define Graphics Characteristics 


BYTE DASH LIST (3) 
DATA DASH_LIST /20,5,10/ 


PARAMETER X1 = 100, Yl = 100, 
1 X2 = 550, Y2 = 550 


CALL X$SET_ BACKGROUND (DPY, GC, DEFINE _COLOR(DPY, SCREEN, 
1 VISUAL, 4)) 


CALL X$SET_LINE_ATTRIBUTES(DPY, GC, 10, 
1 X$C_LINE_DOUBLE_DASH, 0, 0) 


CALL X$SET_DASHES (DPY, GC, 0, DASH_LIST, 3) 
CALL X$DRAW_LINE(DPY, WINDOW, GC, X1, Y1, X2, Y2) 


@ DASH _LIST defines the length of odd and even dashes. The first and 
third elements of the initialization list specify even dashes; the second 
element specifies odd dashes. 


@ The SET LINE ATTRIBUTES routine enables the client to define line 
width, style, cap style, and join style in one call. 


The SET LINE ATTRIBUTES routine has the following format: 


X$SET_LINE_ ATTRIBUTES (display, gc_id, line_width, 
line style, cap _style, join_style) 


The zero cap_style argument specifies the default cap style. 
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© When using the CREATE GC routine to set line dashes, odd and even 
dashes must have equal length. The SET DASHES routine enables the 
client to define dashes of varying length. The SET DASHES routine 
has the following format: 


X$SET_ DASHES (display, gc_id, dash_offset, dash_list, 
dash_list_len) 
The dash_list_len argument specifies the length of the dash list. 


Figure 4-12 Line Defined Using GC Routines 


Line Defined with GC Convenience Routines 





Click MB1 to draw a dashed line. 
Click MB3 to exit. 
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4.4 Copying, Changing, and Freeing Graphics Contexts 


In addition to defining a graphics context, clients can copy defined 
characteristics from one GC data structure into another. To copy a GC 
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data structure, use COPY GC. The COPY GC routine has the following 
format: 


X$COPY_GC(display, src_gc_id, gc_mask, dst_gc_id) 


The ge_mask argument selects values to be copied from the source 
graphics context (sre_gc_id). Use the method described in Section 4.2 
for assigning values to a GRAPHICS CONTEXT. 


The dst_gc_id argument specifies the new graphics context into which the 
server copies values. 


After creating a graphics context structure, change values as needed using 
CHANGE GC. The following code fragment, which alters the values of 
the line drawn by Example 4-1, illustrates changing a graphics context 
structure: 


GC_MASK = X$M_GC_LINE WIDTH .OR. X$M_GC_LINE_STYLE 
XGCVL.X$L_GCVL_LINE WIDTH = 10 
XGCVL.X$L_GCVL_LINE_STYLE = X$C_LINE_SOLID 

CALL X$CHANGE_GC(DPY, GC, GC_MASK, XGCV) 


The example illustrates defining a new line style and width, and changing 
the graphics context to include the new values. 


73.) Using Graphics Characteristics Efficiently 


The server must revalidate a graphics context whenever a client redefines 
it. Causing the server to revalidate a graphics context unnecessarily can 
seriously degrade performance. 


The server revalidates a graphics context when one of the following 
conditions occurs: 


¢ Aclient associates the graphics context with a different window. 


¢ The graphics context clip list changes. Changes in the clip list can 
happen either when a client changes the graphics context clip origin 
or when the server modifies the clip list in response to overlapping 
windows. 


e Any member of the graphics context changes. 
To minimize revalidating the graphics context, submit as a group the 
requests to the server that identify the same window and graphics context. 


Grouping requests enables the server to revalidate the graphics context 
once instead of many times. 
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When it is necessary to change the value of graphics context members 
frequently, creating a new graphics context is more éfficient than 
redefining an existing one, provided the client creates no more than 50 
graphics contexts. 
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Using Color 





Color is one attribute that clients can define when creating a window or a 
graphics object. Depending on display hardware, clients can define color 
as black or white, as shades of gray, or as a spectrum of hues. Section 5.2 
describes color definition in detail. 


Xlib offers clients the choice of either sharing colors with other clients or, 
when hardware supports it, allocating colors for exclusive use. 


A client that does not have to change colors can share them with other 
clients. By sharing colors, the client saves color resources. 


When a client needs to change colors, the client must allocate them for 
its exclusive use. For example, the client might indicate the flow through 
a pipeline by changing colors, rather than redrawing the entire pipeline 
schematic. In this case, the client would allocate for exclusive use colors 
that represent pipeline flow. 


This chapter introduces color management using Xlib and describes how 
to share and allocate color resources. The chapter includes the following 
topics: 


¢ Color fundamentals—A description of pixels and planes, and color 
indices, cells, and maps 


¢ Matching color requirements to display types—How display types 
affect color presentation 


e Sharing color resources—How to share color resources with other 
clients 


¢ Allocating colors for exclusive use—How to reserve colors for a single 
client 


¢ Querying color resources—How to return values of color map entries 


e Freeing color resources—How to release color resources 


The concepts presented in this chapter apply to managing the color of both 
windows and graphic objects. 





Pixels and Color Maps 


The color of a window or graphics object depends on the values of 

pixels that constitute it. The number of bits associated with each pixel 
determines the number of possible pixel values. On a monochrome screen, 
one bit maps to each pixel. The number of possible pixel values is 2. 
Pixels are either zero or one, black or white. 


On a monochrome screen, all bits that define an image reside on one 
plane: an allocation of memory with a one-to-one correspondence between 
bits and pixels. The number of planes is the depth of the screen. 
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5.1 Pixels and Color Maps 
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The depth of intensity or color screens is greater than one. More than one 
bit defines the value of a pixel. Each bit associated with the pixel resides 
on a different plane. 


The number of possible pixel values increases as depth increases. For 
example, if the screen has a depth of four planes, the value of each pixel 
comprises four bits. Clients using a four-plane intensity display can 
produce up to sixteen levels of brightness. Clients using a four-plane 
color display can produce as many as sixteen colors. The number of colors 
possible on any system is equal to 2”, where n is the number of planes. 
Figure 5-1 illustrates the relationship between pixel values and planes. 


Figure 5-1 Pixel Values and Planes 
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Xlib uses color maps to define the color of each pixel value. A color 

map contains a collection of color cells, each of which defines the color 
represented by a pixel value in terms of its red, green, and blue (RGB) 
components. Red, green, and blue components are in the range of zero (off) 
to 65535 (brightest) inclusive. By combining the RGB components, many 
colors can be produced. 


Each pixel value refers to a location in a color map, or is an index into a 
color map. For example, the pixel value illustrated in Figure 5-1 indexes 
color cell 11 in Figure 5-2. 
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Figure 5-2 Color Map, Cell, and Index 
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Most color workstations have a hardware color map that translates pixel 
values into colors for the entire workstation screen. When the color 
definitions from a client’s color map are stored in the hardware color 
map, that color map is said to be installed. If a client’s color map is not 
installed, the client’s windows will be displayed in the wrong color. 


For example, an image processing program that requires 128 colors might 
allocate and store a color map of these values. To alter some colors, 
another client may invoke a color palette program that chooses and mixes 
colors. The color palette program itself requires a color map, which the 
program allocates and installs. 


Because both programs have allocated different color maps, undesirable 
results can be produced. The color palette image may be incorrectly 
displayed when the image processing program runs. The incorrect 
display results because only the image processing color map is installed. 
Conversely, when the color palette program runs, the image processing 
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program may be incorrectly displayed because only the color palette color 
map is installed. 


Xlib reduces the problem of contending for color resources in two ways: 
e Xlib provides a default color map to which all clients have access. 


¢ Clients can allocate either color cells for exclusive use or colors for 
shared use from the default color map. 


By sharing colors, a client can use the same color cells as other clients. 
This method conserves space in the default color map. 


In cases where the client cannot use the default color map and must use 
a new color map, Xlib creates virtual color maps. The use of virtual color 
maps is analogous to the use of virtual memory in a multiprogramming 
environment where many processes must access physical memory. When 
concurrent processes collectively require more color map entries than exist 
in the hardware color map, the color values are swapped in and out of the 
hardware color map. However, swapping virtual color maps in and out of 
the hardware color map causes contention for color resources. Therefore, 
the client should avoid creating color maps whenever possible. 


5.1.1. Installing Color Maps 


The process of loading or unloading color values of the virtual color map 
into the hardware lookup table occurs when a client calls the INSTALL 
COLORMAP or UNINSTALL COLORMAP routines. Typically, the 
privilege to install or remove color maps is restricted to the window 
manager. The window manager installs a color map when a window is 
given focus. The user gives a window focus by clicking on it with the 
mouse and the window manager then installs the color map for that 
window. 


On a system with a single hardware color map, only one window can have 
color map focus at a time. Giving the focus to a new window will cause the 
previous window that had the focus to display in the wrong color. 


Some systems provide multiple color maps in hardware. Multiple windows 
can have color map focus simultaneously. Each window, however, must be 
clicked on to install the correct color map and to get the correct colors. 


Applications that have a window manager running should not make 
direct calls to install color maps. The window manager may reinstall 
different color maps if the client attempts to install a private color map. 
However, on a system with multiple color maps the window manager will 
not remove the private color map. Thus, the client will display in correct 
colors without getting color map focus. 


Some applications are designed to run without a window manager. In this 
case, the application must issue its own install color map requests. 


5.2 


9.2.1 


Using Color 
5.2 Matching Color Requirements to Display Types 


Matching Color Requirements to Display Types 


Visual Types 


The basic philosophy, when using color, is to determine the color needs of 
the client, and then to determine how the system can best support those 
needs. 


This section defines the different visual display types available and 
describes methods to choose the appropriate type for the client. 


Each screen has a list of visual types associated with it. The visual type 
identifies the characteristics of the screen, such as color or monochrome 
capability. Visual types partially determine the appearance of color on 
the screen and determine how a client can manipulate color maps for a 
specified screen. 


Color maps can be manipulated in a variety of ways on some hardware, 
in a limited way on other hardware, and not at all on yet other hardware. 
For example, a screen may be able to display a full range of colors or a 
range of grays only, depending on its visual type. 


VMS DECwindows defines the following visual types: 

¢ Pseudocolor 

e Gray scale 

¢ Direct color 

¢ True color 

e Static gray 

e §©6Static color 

Pseudocolor is a full-color device. A pixel value indexes a color map 
composed of red, green, and blue definitions. Each definition in the color 
map stores the red, green, and blue component values for one color. The 
color index refers directly to a single entry in the color map. RGB values 
can be changed dynamically if a pixel has been allocated for exclusive 


use. Pseudocolor is the default visual type on Digital 4-plane and 8-plane 
systems. 


In Figure 5-3, the pseudocolor illustration shows a pixel value of 2 
(00000010 in binary) indexing entry 2 in the color map. 


Gray scale is a black and white device. Gray scale is the same as 
pseudocolor except that a pixel value indexes a color map that produces 
shades of gray only. The gray shades are defined in a color map with each 
definition having just one component that defines the level of the white 
intensity. 


Refer to Figure 5~3 for an illustration of the gray scale visual type. 


5-5 


- Using Color 
5.2 Matching Color Requirements to Display Types 


Direct color is a full-color device. Both the pixel value and the color 
map are separated into three independent parts, one each for red, green, 
and blue. The red part of the pixel indexes the red color map, the green 
indexes the green color map, and the blue indexes the blue color map. A 
complete color definition comprises the three components in each color 
map. RGB values can be changed dynamically if a pixel has been allocated 
for exclusive use. | 


In Figure 5-3, the direct color illustration shows that a pixel value of 90 
(01011010 in binary) is separated into three values by using color masks, 
which are defined in the visual info data structure. (Refer to Section 5.2.3 
for information about the visual info data structure.) Each color mask 
indicates which bits of the pixel value reference which color map. Each 
value is then used to index one of the three structures. In this case, entry 
2 is indexed in the red color map, entry 6 in the green color map, and 
entry 2 in the blue color map. 


True color is a full-color device. True color is the same as direct color 
except that the color map has predefined read-only RGB values in 
ascending order. True color is the default visual type on Digital’s 24-plane 
system. 


Refer to Figure 5-3 for an illustration of the true color visual type. 


Static gray is a black and white device. Static gray is the same as gray 
scale except that the values in the color map are read-only. Static gray 
with a two-entry color map can be thought of as monochrome. 


Refer to Figure 5-3 for an illustration of the static gray visual type. 


Static color is a full-color device and is the same as pseudocolor except 
that the color map has predefined, read-only, server-dependent values in 
an undefined, server-dependent order. 
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Figure 5-3 Visual Types and Color Map Characteristics 
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5.2.2 Determining the Default Visual Type 


Before defining colors, use the following method to determine the default 
visual type of a screen: 


1 Use the DEFAULT VISUAL OF SCREEN routine to determine the 
identifier of the visual. Xlib returns the identifier to a visual data 
structure. 


2 Refer to the X$L_VISU_CLASS member of the data structure to 
determine the visual type. 


The following example illustrates one method to determine the default 
visual type of a screen: 


CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 


RECORD /XS$VISUAL/ VISU 
IF (VISU.X$L_VISU_CLASS .EQ. X$C_TRUE_COLOR .OR. 
1 VISU.X$L_VISU_CLASS .EQ. X$C_PSEUDO COLOR .OR. 


1 VISU.X$L_VISU_CLASS .EQ. X$C_DIRECT_COLOR .OR. 


1  VISU.X$L_VISU_CLASS .EQ. X$C_STATIC_COLOR) THEN 


5.2.3 Determining Multiple Visual Types 


On some systems, a single display can support multiple screens. Each 
screen can have several different visual types supported at different 
depths. Xlib provides routines that allow a client to search and choose 
the appropriate visual type on the system by using the visual info data 
structure. 


Figure 5—4 illustrates the visual info data structure. 
Figure 5-4 Visual Info Data Structure 
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Figure 5-4 (Cont.) Visual Info Data Structure 











x$l_visl_red_mask 20 
x$l_visl_green_mask 24 
x$l_visl_blue_mask 28 
. xX$l_visl_colormap_size 32 
x$I_visl_bits_per_rgb 36 
Table 5-1 describes the members of the visual info data structure. 
Table 5-1 Visual Info Data Structure Members 
Member Name Contents 
X$A_VISL_VISUAL A pointer to a visual data structure that is returned 
to the client. 
X$L_VISL_VISUAL_ID The id of the visual that is returned by the server. 
X$L_VISL_SCREEN The specified screen of the display. 
X$L_VISL_DEPTH The depth in planes of the screen. 
X$L_VISL_CLASS The class of the visual (X$C_PSEUDO_COLOR, 
X$C_GRAY_SCALE, X$C_DIRECT_COLOR, 
X$C_TRUE_COLOR, X$C_STATIC_COLOR, 
X$C_STATIC_GRAY). 
X$L_VISL_RED_MASK Definition of the red mask. ' 
X$L_VISL_GREEN_MASK Definition of the green mask. ' 
X$L_VISL_BLUE_MASK Definition of the blue mask. ' 
X$L_VISL_COLORMAP_ SIZE Number of available color map entries. 
X$L_VISL_BITS_PER_RGB Number of bits that specifies the number of distinct 


red, green and blue values. Actual RGB values 
are unsigned 16-bit numbers. 





‘The red mask, green mask, and blue mask are only defined for the direct color and true color 
visual types. 





Use the GET VISUAL INFO routine to return a list of visual structures 
that match a specified template. 


The GET VISUAL INFO routine has the following format: 
X$GET_VISUAL_INFO (display, vinfo_mask, vinfo_template, 


num_items_return [,items_return] [,items_size] 
{,items_buff_return]) 
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Use the MATCH VISUAL INFO routine to return the visual information 
for a visual type that matches the specified depth and class for a screen. 
Because multiple visual types can exist that match the specified depth and 
class, the exact visual chosen is undefined. 


Note that the MATCH VISUAL INFO routine is a convenience routine 
that matches one visual of a particular class and depth. The GET VISUAL 
INFO routine, however, can find any number of visuals that match any 
combination of characteristics. 


The MATCH VISUAL INFO routine has the following format: 


XSMATCH_ VISUAL _INFO(display, screen_number, depth, 
class, vinfo_return) 





5.3 Sharing Color Resources 
Xlib provides the following ways to share color resources: 
¢ Using named VMS DECwindows colors 
e Specifying exact color values 
The choice of using a named color or specifying an exact color depends on 
the needs of the client. For instance, if the client is producing a bar graph, 
specifying the named VMS DECwindows color “Red” as a color value may 
be sufficient, regardless of the hue that VMS DECwindows names “Red”. 


However, if the client is reproducing a portrait, specifying an exact red 
color value might be necessary to produce accurate skin tones. 


Note that because of differences in hardware, no two monitors display 
colors exactly the same, even though the same named colors are specified. 


For a list of VMS DECwindows named colors, see Appendix C. 


5.3.1. Using Named VMS DECwindows Colors 


VMS DECwindows includes named colors that clients can share. To use a 
named color, call the ALLOC NAMED COLOR routine. ALLOC NAMED 
COLOR determines whether the color map defines a value for the specified 
color. If the color exists, the server returns the index to the color map. If 
the color does not exist, the server returns an error. 


Example 5-1 illustrates specifying a color using ALLOC NAMED COLOR. 
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Example 5-1 Using Named VMS DECwindows Colors 





INTEGER*4 FUNCTION DEFINE _COLOR(DISP, SCRN, VISU, N) 
INCLUDE 'SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DISP, SCRN, N 

RECORD /XSVISUAL/ VISU ! visual type 

RECORD /X$COLOR/ SCREEN_COLOR 

INTEGER*4 STR_SIZE, STATUS, COLOR_MAP 

CHARACTER*15 COLOR_NAME (3) 

DATA COLOR_NAME /’DARK SLATE BLUE’, ‘’LIGHT GREY ‘, ‘FIREBRICK 


IF (VISU.X$L_VISU_CLASS .EQ. X$C_TRUE_COLOR .OR. 

1  VISU.X$L_VISU_CLASS .EQ. X$C_PSEUDO_COLOR .OR. 

1  VISU.X$L_VISU_CLASS .EQ. X$C_DIRECT COLOR .OR. 

1  VISU.X$L_VISU_CLASS .EQ. X$C_STATIC_COLOR) .THEN. 


COLOR_MAP = XSDEFAULT_COLORMAP_OF_ SCREEN (SCRN) 


STATUS = STRSTRIM(COLOR_NAME(N), 

1 COLOR_NAME(N), STR_SIZE) 

STATUS = X$ALLOC_NAMED COLOR(DISP, COLOR MAP, 

1 COLOR _NAME(N) (1:STR SIZE), SCREEN COLOR) 


IF (STATUS) THEN 

DEFINE COLOR = SCREEN_COLOR.X$L_COLR_PIXEL 
ELSE 

WRITE (6,*) ‘Color not allocated!’ 

CALL LIBSSIGNAL (%VAL (STATUS) ) 

DEFINE_COLOR = 0° 


END IF 
ELSE 
IF (N .EQ. 1 .OR. N .EQ. 3) 
1 DEFINE COLOR = X$BLACK_PIXEL OF _SCREEN (DISP) 
IF (N .EQ. 2 ) 
1. DEFINE COLOR =. X$WHITE PIXEL OF SCREEN (DISP) 
END IF 
RETURN 
END 


a 





@ Allocate storage for a color data structure that defines the closest RGB 
values supported by the hardware. 


For an illustration of the color data structure, see Section 5.3.2. 


@® Create an array to store the names of predefined VMS DECwindows 
colors used by the client. In the sample program, the client uses 
three named colors: dark slate blue, light grey, and firebrick. When 
allocating a color, the client refers to the array element that stores the 
appropriate named VMS DECwindows color. 


© Xlib requires clients to pass names of predefined colors without 
padding. In the DEFINE_COLOR function, the names of predefined 
colors are stored in an array of three 15-byte members. Because the 
names “light grey” and “firebrick” require less than 15 bytes of storage, 
they are padded. 
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To pass the names without padding, use the system-defined procedure 
STR$TRIM, which returns to the STR_SIZE variable the length of the 
string minus any trailing blanks. 


@ The ALLOC NAMED COLOR routine has the following format: 


XSALLOC_NAMED_COLOR(display, colormap_id, color_name, 
[screen_def return], [exact_def_return]) 


The client refers to array COLOR_NAME to pass the name of the 
color. The client passes only the substring that contains the predefined 
name; blanks used to pad the array are ignored. 


Specifying Exact Color Values 
To specify exact color values, use the following method: 
1 Assign values to a color data structure 


2 Call the ALLOC COLOR routine, specifying the color map from 
which the client allocates the definition. ALLOC COLOR returns a 
pixel value and changes the RGB values to indicate the closest color 
supported by the hardware. 


Xlib provides a color data structure enabling clients to specify exact color 
values when sharing colors. (Routines that allocate colors for exclusive 
use and that query available colors also use the color data structure. For 
information about using the color data structure for these purposes, see 
Section 5.4.) 


Figure 5—5 illustrates the color data structure. 


Figure 5-5 Color Data Structure 







x$l_colr_pixel 0 
; 
x$b_colr_pad x$b_colr_flags x$w_colr_blue 8 





Table 5-2 describes the members of the data structure. 


Table 5—-2 Color Data Structure Members 


Member Name . Contents 


X$L_COLR_PIXEL Pixel value 


(continued on next page) 
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Table 5-2 (Cont.) Color Data Structure Members 








Member Name Contents 

X$W_COLR_RED Defines the red value of the pixel ' 

X$W_COLR_GREEN Defines the green value of the pixel ' 

X$W_COLR_BLUE Defines the blue value of the pixel | 

X$B_COLR_FLAGS Defines which color components are to be changed in 
the color map. Possible flags are as follows: 
x$m_do_red Sets red values 
x$m_do_green Sets green values 

. x$m_do_blue Sets blue values 
X$B_COLR_PAD Makes the data structure an even length 


'Color values are scaled between 0 and 65535. “On full” in a color is a value of 65535, 
independent of the number of planes of the display. Half brightness in a color is a value of 
32767; off is a value of 0. This representation gives uniform results for color values across 
displays with different color resolution. 


Example 5-2 illustrates how to specify exact color definitions. 


Example 5-2 Specifying Exact Color Values 





Cc 
Cc 


Create color 


INTEGER*4 FUNCTION DEFINE _COLOR(DISP, SCRN, VISU, N) 


INCLUDE ’SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DISP, SCRN, N 

RECORD /X$VISUAL/ VISU ! visual type 
RECORD /XSCOLOR/ COLORS (3) 

INTEGER*4 STATUS, COLOR _MAP 

INTEGER*4 FLAGS 


IF (VISU.X$L_VISU_CLASS .EQ. X$C_TRUE_COLOR .OR. 


1 
1 
1 


VISU.X$L_VISU_CLASS -EQ. X$C_PSEUDO_COLOR -OR. 
VISU.X$L_VISU_CLASS .EQ. X$C_DIRECT_ COLOR .OR. 
VISU.X$L_VISU_CLASS .EQ. X$C_STATIC_COLOR) THEN 
COLOR_MAP = XSDEFAULT_COLORMAP_OF_SCREEN (SCRN) 
IF (N .EQ. 1) THEN 
COLORS (N) .X$W_COLR_RED = 59904 
COLORS (N) .X$W_COLR_GREEN = 44288 
COLORS (N) .X$W_COLR_BLUE = 59904 
STATUS = XS$ALLOC_COLOR(DISP, COLOR_MAP, COLORS (N) ) 
IF (STATUS) THEN 
DEFINE_COLOR = COLORS (N) .X$L_COLR_PIXEL 
ELSE 
WRITE (6,*) ‘Color not allocated!’ 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
DEFINE_COLOR = 0 
END IF 
ELSE IF (N. EQ. 2) THEN 
COLORS (N) .X$B_COLR_FLAGS = FLAGS 
COLORS (N) .X$W_COLR_RED = 65280 
COLORS (N) .XS$W_COLR_GREEN = 0 


(continued on next page) 
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COLORS (N) .X$W_COLR_BLUE = 32512 
STATUS = XSALLOC_COLOR(DISP, COLOR_MAP, COLORS (N) ) 
IF (STATUS) THEN 

DEFINE COLOR = COLORS (N) .X$L_COLR_PIXEL 
ELSE 

WRITE (6,*) ‘Color not allocated!’ 

CALL LIBSSIGNAL (%VAL (STATUS) ) 

DEFINE COLOR = 0 
END IF 

ELSE IF (N. EQ. 3) THEN 

COLORS (N) .X$B_COLR_FLAGS = FLAGS 
COLORS (N) .X$W_COLR_RED = 37632 
COLORS (N) .X$W_COLR_GREEN = 56064 
COLORS (N) .X$W_COLR_BLUE = 28672 
STATUS = XSALLOC_COLOR (DISP, COLOR_MAP, COLORS (N) ) 
IF (STATUS) THEN 

DEFINE COLOR = COLORS (N) .X$L_COLR_PIXEL 
ELSE 

WRITE (6,*) ‘Color not allocated!’ 

CALL LIBSSIGNAL (%VAL (STATUS) ) 

DEFINE COLOR = 0 


END IF 
END IF 

ELSE 

IF (N .EQ. 1 .OR. N .EQ. 3) 
1 DEFINE COLOR = X$BLACK_PIXEL OF SCREEN (DISP) 

IF (N .EQ. 2 ) 
1 DEFINE COLOR = X$WHITE PIXEL OF_SCREEN (DISP) 
END IF 
RETURN 
END 





0 Define color values in the first of three color data structures. 


@ After defining RGB values, call the ALLOC COLOR routine. ALLOC 
COLOR allocates shared color cells on the default color map and 
returns a pixel value for the color that matches the specified color most 
closely. 


5.4 Allocating Colors for Exclusive Use 


If a client does not need to change color values, it should share colors 

by using the methods described in Section 5.3. Sharing colors saves 
resources. However, a client that changes color values must allocate them 
for its exclusive use. 


Xlib provides two methods for allocating colors for a client’s exclusive use. 
First, the client can allocate cells and store color values in the default color 
map. Second, if the default color map does not contain enough storage, 

or if the default color map is read-only (such as true color), the client 

can create its own color map using a writable visual type and store color 
values in it. In addition, when creating a color map, the client can allocate 
all entries in the color map for its exclusive use. Refer to the CREATE 
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COLORMAP routine in Section 5.4.1 for more information about allocating 
all entries in a color map. 


This section describes how to specify a color map, how to allocate cells for 
exclusive use, and how to store values in the color cells. 


Specifying a Color Map 


Clients can either use the default color map and allocate its color cells for 
exclusive use or create their own color maps. 


If possible, use the default color map. Although a client can create color 
maps for its own use, the hardware color map storage is limited. When 
a client creates its own color map, the map must be installed into the 
hardware color map before the client map can be used. If the client color 
map is not installed, the client may be displayed using a different color 
map and possibly display the wrong color. Using the default color map 
eliminates this problem. See Section 5.1 for information about how Xlib 
handles color maps. 


To specify the default color map, use the DEFAULT COLORMAP routine. 
DEFAULT COLORMAP returns the identifier of the default color map. 


If the default color map does not contain enough resources, the client can 
create its own color map. 


To create a color map, use the following method: 


1 Using one of the methods described in Section 5.2, determine the 
visual type of a specified screen. 


2 Call the CREATE COLORMAP routine. 


The CREATE COLORMAP routine creates a color map for the specified 
window and visual type. Note that CREATE COLORMAP can only be 
used with pseudocolor, gray scale, and direct color visual types. 


The CREATE COLORMAP routine has the following format: 
XSCREATE_COLORMAP (display, window_id, visual_struc, alloc) 


The alloc argument specifies whether the client creating the color map 
allocates all of the color map entries for its exclusive use or creates a 
color map with no allocated color map entries. To allocate all entries for 
exclusive use, specify the constant x$c_alloc_all. To allocate no defined 
map entries, specify the constant x$c_alloc_none. The latter is useful 
when two or more clients are to share the newly created color map. 


See Section 5.4.2 for information about allocating colors. 


Allocating Color Cells 


After specifying a color map, allocate color cells in it. 
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Use the ALLOC COLOR CELLS routine or ALLOC COLOR PLANES to 
allocate color resources. Either routine can be used; however, ALLOC 
COLOR CELLS allocates colors according to the pseudocolor model. The 
ALLOC COLOR PLANES routine allocates color resources according to 
a direct color model. See Section 5.2 for information about these color 
models. 


Example 5-3 illustrates how to allocate colors for exclusive use. The 
program creates a color wheel that rotates when the user presses MB1. 


Note: The following example will only run on systems that have 


pseudocolor or direct color default visual types. 


Example 5-3 Allocating Colors for Exclusive Use 





PROGRAM COLOR_WHEEL 
INCLUDE ’ SYSSLIBRARY : DECWSXLIBDEF’ 


aaa 


INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 


RECORD 
RECORD 
RECORD 
RECORD 
RECORD 
RECORD 


uy 


OFFSET _X 
OFFSET _Y 


Initializ 


DPY 
SCREEN 

WINDOW 

GC_MASK 

ATTR_MASK 

Gc 

OFFSET X 

OFFSET Y 

CMAP 

PIXMAP 

WIDTH, HEIGHT 

BUTTON_IS DOWN 

FULL _COUNT 

STATUS, FUNC 

WINDOW _X, WINDOW_Y, DEPTH 


/X$VISUAL/ VISUAL 

/X$COLOR/ COLORS (128) 
/X$SET_WIN_ATTRIBUTES/ XSWDA 
/X$GC_VALUES/ XGCVL 
/X$SIZE_HINTS/ XSZHN 
/X$EVENT/ EVENT 

PARAMETER 


WINDOW_W = 600, WINDOW_H = 
BACK_W = 800, BACK_H = 800 


100 
100 


600, 


i 


e display id and screen id 


DPY = XS$OPEN_DISPLAY () 


SCREEN = 
STATUS = 


Create the 


X$DEFAULT_SCREEN_OF_ DISPLAY (DPY) 


XS$SYNCHRONIZE(DPY, 1, FUNC) 


WINDOW window 


WINDOW_X 
WINDOW _Y = 


(X$WIDTH_OF_SCREEN(SCREEN) - WINDOW_W) / 2. 
(X$HEIGHT OF _SCREEN(SCREEN) - WINDOW_H) / 2 





(continued on next page) 
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Example 5-3 (Cont.) Allocating Colors for Exclusive Use 





Qe0an 


' —- |e ome) 


qaqa @eea 


qaaa 


aan 


aaa 


DEPTH = X$DEFAULT_DEPTH_OF_SCREEN (SCREEN) 
CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 
ATTR_MASK = X$M_CW_EVENT MASK .OR. X$M_CW_BACK PIXEL 


XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE .OR. XSM_BUTTON PRESS 
al -OR. XS$M_EXPOSURE .OR. X$M_BUTTON RELEASE .OR. 
2: X$M_STRUCTURE_ NOTIFY 


XSWDA.X$L_SWDA_BACKGROUND_PIXEL = 
1 XSBLACK_ PIXEL _OF_SCREEN (SCREEN) 


WINDOW = XSCREATE WINDOW (DPY, 

1 X$ROOT_WINDOW_OF_SCREEN (SCREEN) , 

1 WINDOW X, WINDOW | Y, WINDOW _W, WINDOW_H, 0, 

ul DEPTH, XS INPUT _OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


Creat2 graphics context 


GC = XSCREATE_GC (DPY, WINDOW, 0, 0) 

CALL XSSET_ FOREGROUND (DPY, GC, XSWHITE PIXEL OF SCREEN (SCREEN) ) 
Create the pixmap used for backing store 

PIXMAP = XSCREATE _ PIXMAP (DPY, X$ROOT WINDOW (DPY, 

1 X$DEPAULT | SCREEN (DPY)), BACK_W, BACK_H, DEPTH) 

CALL X$FILL_ RECTANGLE (DPY, PIXMAP, GC, 0, 0, BACK_W, BACK_H) 


Create the initial colors for the wheel 


CALL CREATE COLORS (DPY, SCREEN, VISUAL, COLORS, CMAP, FULL COUNT) 


Create the wheel 


CALL CREATE WHEEL (DPY, SCREEN, GC, PIXMAP, COLORS) 
Define the size and name of the WINDOW window 


XSZHN.X$L_SZHN_X = 212 

XSZHN.X$L_SZHN_Y = 132 

XSZHN. X$L_ SZHN | WIDTH = 600 

XSZHN. X$L_ SZHN_| HEIGHT = 600 

XSZHN. X$L_SZHN FLAGS = X$M _P_POSITION .OR. X$M_P_SIZE 


CALL X$SET_NORMAL HINTS (DPY, WINDOW, XSZHN) 
CALL X$STORE_NAME (DPY, WINDOW, 
1 ’Color Wheel: Press MB1 to Rotate or Click MB2 to Exit.’) 


Map the window 


CALL XSMAP_WINDOW(DPY, WINDOW) 


Handle events 


DO WHILE (.TRUE.) 
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CALL X$NEXT_EVENT(DPY, EVENT) 


IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN 
CALL X$COPY_AREA(DPY, PIXMAP, WINDOW, GC, 


1 OFFSET _X + EVENT.EVNT_EXPOSE.X$L_EXEV_X, 
1 OFFSET Y + EVENT.EVNT_EXPOSE.X$L_EXEV_Y, 
1 EVENT .EVNT_EXPOSE.X$L_EXEV_WIDTH, 
1 EVENT .EVNT_EXPOSE.X$L_EXEV_ HEIGHT, 
1 EVENT .EVNT_EXPOSE.X$L_EXEV_X, 
1 EVENT .EVNT_EXPOSE.X$L_EXEV_Y) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT.EVNT BUTTON.X$L_BTEV BUTTON .EQ. X$C_BUTTON1) THEN 
BUTTON _IS DOWN = 1 
IF (BUTTON_IS DOWN .EQ. 1) THEN 
CALL CHANGE COLORS (DPY, CMAP, COLORS, FULL_COUNT) 
END IF 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 
aE EVENT.EVNT BUTTON.X$L_BTEV BUTTON .EQ. X$C_BUTTON2) THEN 
CALL SYSSEXIT(%VAL (1) ) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON RELEASE) THEN 
BUTTON_IS DOWN = 0 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_CONFIGURE_NOTIFY) THEN 
OFFSET _X = 
1 (BACK_W - EVENT.EVNT_CONFIGURE.X$L_CFEV_WIDTH) /2 
OFFSET Y = 
(BACK_H - EVENT.EVNT_CONFIGURE.X$L_CFEV_HEIGHT) /2 
END IF 
END DO 
END 


CREATE COLORS SUBROUTINE 


SUBROUTINE CREATE COLORS (DISP, SCRN, VISU, CLRS, MAP, FC) 
INCLUDE ’ SYSSLIBRARY:DECWS$XLIBDEF’ 


INTEGER*4 DISP, SCRN, MAP, FC 
INTEGER*4 PIXELS (128) 
INTEGER*4 CONTIG, STATUS 
INTEGER*4 PLANE MASKS (128) 


RECORD /XSVISUAL/ VISU 
RECORD /XSCOLOR/ CLRS (128) 
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IF (VISU.X$L_VISU_CLASS .EQ. X$C_PSEUDO_COLOR .OR. 
1 VISU. XSL | VISU_ CLASS .EQ. X$C_] DIRECT | COLOR) THEN 


MAP = XSDEFAULT_COLORMAP_OF_SCREEN (SCRN) 
FC = XSDISPLAY _CELLS (DISP, “X$DEFAULT | SCREEN (DISP) ) 
IF (FC .GT. 128) THEN 
FC = 128 
END IF 
STATUS = X$ALLOC_COLOR_CELLS(DISP, MAP, CONTIG, PLANE MASKS, 
1 0, PIXELS, FC) 
IF (STATUS .EQ. 0) THEN 
CALL SYSSEXIT(%VAL (1) ) 
END IF 
CALL LOAD COLORMAP (DISP, MAP, CLRS, PIXELS, FC) 
ELSE 
CALL SYSSEXIT(%VAL(1) ) 
END IF 


RETURN 
END 


LOAD COLORMAP SUBROUTINE 


SUBROUTINE LOAD COLORMAP (DIS, MP, COLR, PIXS, COUNT) 
INCLUDE ‘SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DIS, MP, COUNT 
INTEGER*4 PIXS (128) 
INTEGER*4 I, C, FLAGS 
INTEGER*2 J(2) 
EQUIVALENCE (C, J(1)) 
REAL*16 H, R, G, B 


RECORD /X$COLOR/ COLR (128) 


FLAGS = X$M_DO_RED .OR. X$M_DO GREEN .OR. X$M_DO BLUE 
DO I = 1, COUNT 
COLR(I) .X$L_COLR PIXEL = PIXS(I) 
COLR(I) .X$B_COLR_FLAGS = FLAGS 
H = I * 360./(COUNT + 1.) 
CALL HLS TO RGB(H, .5, .5, R, G, B) 
C = R * 65535.0 
COLR(I) .X$W_COLR_RED = J(1) 
C = G * 65535.0 
COLR(I) .X$W_COLR_GREEN = J(1) 
C = B * 65535.0 
COLR(I) .X$W_COLR_BLUE = J(1) 
END DO 
CALL X$STORE_COLORS(DIS, MP, COLR, COUNT) 


RETURN 
END 


HLS TO_RGB SUBROUTINE 


SUBROUTINE HLS TO RGB(HUE, LGHT, SATUR, RD, GRN, BLU) 
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REAL*16 VALUE 

REAL*16 HUE, LGHT, SATUR 
REAL*16 RD, GRN, BLU 
REAL*16 M1, M2 


IF (LGHT .LT. .05) THEN 
M2 = L * (1 + SATUR) 

ELSE 
M2 

END IF 

M1 = 2 * LGHT - M2 

IF (SATUR .EQ. 0) THEN 


LGHT + SATUR - (LGHT * SATUR) 


RD = LGHT 

GRN = LGHT 

BLU = LGHT 
ELSE 


RD = VALUE(M1, M2, (HUE + 120.)) 


GRN = VALUE(M1, M2, (HUE + 000.)) 
BLU = VALUE(M1, M2, (HUE - 120.)) 
END IF 
RETURN 


END 


CREATE WHEEL SUBROUTINE 


Orca 


INCLUDE ’ SYS$LIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DISP, SCRN, GRAPH CON, PMAP 
INTEGER*4 I, J, PIXEL 

INTEGER*4 X_CENT, Y_ CENT 

REAL*16 X, Y, XCENT_F, YCENT_F 


RECORD /X$COLOR/ CLRS (128) 
RECORD /X$POINT/ PGON (387) 


PARAMETER PMAP WIDTH = 800, PMAP_HEIGHT = 800 


SUBROUTINE CREATE WHEEL(DISP, SCRN, GRAPH CON, PMAP, CLRS) 
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X_ CENT = PMAP_WIDTH/2 

Y_CENT = PMAP_HEIGHT/2 

PGON (1) .X$W_GPNT_X = PMAP_ WIDTH 
PGON (1) .X$W_GPNT_Y = PMAP_HEIGHT/2 
I= 2 

DO WHILE (I .LT. 384) 


PGON (I) .X$W_GPNT_X = X_CENT 
PGON (I) .X$W_GPNT_Y = Y CENT 
I=I+3 

END DO 

I= 2 

PIXEL = 1 


DO WHILE (PIXEL .LT. 129) 
XCENT_F = X_CENT 
YCENT F = Y CENT 
X = COS ((QFLOAT (PIXEL) /128) *2*3.14159) 
Y = SIN((QFLOAT (PIXEL) /128) *2*3.14159) 
PGON(I + 1).X$W_GPNT_X = (X * XCENT_F) + X_CENT 
PGON(I + 1).X$W_GPNT Y = (Y * YCENT F) + Y_CENT 
PGON(I + 2).X$W_GPNT X = PGON(I + 1) .X$W_GPNT_X 
PGON(I + 2).X$W_GPNT Y = PGON(I + 1).X$W_GPNT Y 
CALL X$SET_FOREGROUND (DISP, GRAPH CON, CLRS((I+1)/3) .X$L_COLR_PIXEL) 
CALL X$FILL_POLYGON(DISP, PMAP, GRAPH_CON, PGON(I-1), 3, 


1 X$C_CONVEX, X$C_COORD MODE ORIGIN) 
Loe Ee 3 
PIXEL = PIXEL + 1 

END DO 

RETURN 

END 


CHANGE COLORS SUBROUTINE 


SUBROUTINE CHANGE COLORS (DISP, MAP, CLRS, CNT) 
INCLUDE ’ SYSSLIBRARY: DECWSXLIBDEF’ 


INTEGER*4 DISP, MAP, CNT, PENDING 
INTEGER*4 I, TEMP 


RECORD /XSCOLOR/ CLRS (128) 


DO WHILE (XS$PENDING(DISP) .EQ. 0) 
TEMP = CLRS(1) .X$L_COLR_PIXEL 
I=1 
DO WHILE (I .LT. CNT) 
CLRS (I) .X$L_COLR_PIXEL = CLRS(I + 1).X$L_COLR_PIXEL 
I=] +1 
END DO 
CLRS (CNT) .X$L_COLR_PIXEL = TEMP 
CALL X$STORE COLORS(DISP, MAP, CLRS(1), CNT) 
END DO 


RETURN 
END 
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VALUE FUNCTION 
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REAL*16 FUNCTION VALUE(N1, N2, HUE) 
REAL*16 N1, N2, HUE, VAL 


IF (HUE .GT. 360.) THEN 
HUE = HUE - 360. 
END IF 
IF (HUE .LT. 0) THEN 
HUE = HUE + 360. 
END IF 
IF (HUE .LT. 60) THEN 
VAL = N1 + (N2 - N1) * HUE/60. 
ELSE IF (HUE .LT. 180.) THEN 
VAL = N2 
ELSE IF (HUE .LT. 240) THEN 
VAL = N1 + (N2 - N1) * (240. -— HUE)/60. 


ELSE 

VAL = N1 
END IF 
VALUE = VAL 
RETURN 
END 


@ The client uses a pixmap as a backing store for the color wheel. When 
a user reconfigures the color wheel window, the client copies the color 
wheel from the pixmap into the resized window. For information about 
creating and using pixmaps, see Chapter 7. 


@ After creating the pixmap for backing store, the client creates colors 
for the wheel and the wheel itself. For details about these subroutines, 
see callouts 8, 9, and 10. 


© When the user reconfigures the window, the server generates an 
expose event. In response to the event, the client copies the pixmap 
into the exposed area, which is calculated using the offset from the 
original to the new position of the window. For information about 
handling exposure events, see Chapter 9. 


@ The client calculates the offset from the original window position in 
response to a configure notify event. The server issues a configure 
notify event each time the user resizes the color wheel window. For 
information about handling configure notify events, see Chapter 9. 


© The client-defined CREATE_COLORS routine allocates color cells for 
the exclusive use and stores initial color values in the color map. 


© The client uses the default color map, specifying that only 128 color 
cells be allocated. After allocating color cells, the client calls the 
client-defined LOAD_COLORMAP routine to define color values. 


@ The LOAD COLORMAP routine defines 128 colors and stores them in 
the color map. 
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© Colors are defined initially using the Hue, Light, Saturation (HLS) 
system. The values of color hues vary, while values for light and 
saturation remain constant. After a color has been defined using HLS, 
the color is converted into RGB values by the client-defined HLS_TO_ 
RGB routine. When all colors are defined, the client stores them in the 
color map by calling the client-defined STORE COLORS routine. 


© The client-defined CREATE_WHEEL routine defines the wheel used to 
display colors and specifies initial color values. 


@ The wheel is composed of polygons. Each polygon is defined by three 
points, one in the center of the wheel and two at the circumference. 
After the initial polygon is specified, each polygon shares one point 
with the polygon previously defined, as Figure 5-6 illustrates. 


To define each point the client uses a point data structure, which is 
described in Chapter 6. After defining a polygon, the client fills it with 
a specified foreground color. 


@® The rotation of the color wheel is accomplished by changing values in 
the color map. As long as there are no pending events, and the user 
is pressing MB1, the client-defined CHANGE_COLORS routine shifts 
color values by one. 


Figure 5-6 illustrates how the color wheel in Example 5-3 is composed of 
a set of polygons. 


5-23 


Using Color 
5.4 Allocating Colors for Exclusive Use 


Figure 5—6 Polygons That Define the Color Wheel 


x Pixmap 
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When allocating colors from any shared color map, the client may exhaust 
the resources of the color map. In this case, Xlib provides a routine for 
copying the default color map entries into a new client-created color map. 


To create a new color map when the client exhausts the resources of a 
previously-shared color map, use the COPY COLORMAP AND FREE 
routine. The routine creates a color map of the same visual type and 

for the same screen as the previously shared color map. The previously- 
shared color map can be either the default color map or a client-created 
color map. The COPY COLORMAP AND FREE routine has the following 
format: 


X$COPY_COLORMAP_AND FREE(display, colormap_id) 


COPY COLORMAP AND FREE copies all allocated cells from the 
previously shared color map to the new color map, keeping color values 
intact. The new color map is created with the same value of the argument 
alloc as the previously shared color map and has the following effect on 
the new color map entries: 
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Value of alloc Effect 

x$c_alloc_all All entries are copied from the previously shared color map 
and are then freed to create writable map entries. 

x$c_alloc_none The entries moved are all pixels and planes that have been 


allocated using the following routines and that have not been 
freed since they were allocated: ALLOC COLOR, ALLOC 
NAMED COLOR, ALLOC COLOR CELLS, ALLOC COLOR 
PLANES. 


5.4.3. Storing Color Values 


After allocating color entries in the color map, store RGB values in the 
color map cells using the following method: 


1 Assign color values to the color data structure and set the X$B_COLR_ 
FLAGS member to indicate the components to be changed. Normally, 
all flags should be set. 


2 Call the STORE COLOR routine to store one color, the STORE 
COLORS routine to store more than one color, or the STORE NAMED 
COLOR routine to store a named color. 


- The STORE COLOR routine has the following format: 
XS$STORE COLOR(display, colormap_id, screen_def_return) 
The STORE COLORS routine has the following format: 


X$STORE_COLORS (display, colormap_id, screen_defs_return, 
num_colors) 


The STORE NAMED COLOR routine has the following format: 


X$SSTORE_ NAMED COLOR(display, colormap_id, color name, 
pixel, flags) 


Refer to Example 5-3 for an example of using the STORE COLORS 
routine. 





5.5 Freeing Color Resources 


To free storage allocated for client colors, call the FREE COLORS routine. 
FREE COLORS releases all storage allocated by the following color 
routines: ALLOC COLOR, ALLOC COLOR CELLS, ALLOC NAMED 
COLORS, ALLOC COLOR PLANES. 


To delete the association between the color map ID and the color map, use 
the FREE COLORMAP routine. FREE COLORMAP has no effect on the 
default color map of the screen. If the color map is an installed color map, 
FREE COLORMAP removes it. 


5-25 


5.6 


Using Color 


5.6 Querying Color Map Entries 





Querying Color Map Entries 
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Xlib provides routines to return both the RGB values of the color map 
index and of a named color. 


To query the RGB values of a specified pixel in the color map, use the 
QUERY COLOR routine. The pixel value to look up is specified in the 
pixel member of the color data structure. The RGB components of the 
color value are returned in the red, green, and blue members of the data 
structure. 


To query the RGB values of an array of pixel values, use the QUERY 
COLORS routine. The values returned are the values passed in the pixel 
member of the color data structure. Note that if the color map entry 
being queried is undefined, the value returned by QUERY COLOR will not 
necessarily correspond to the color displayed on the screen. 


To look up the values associated with a named color, use the LOOKUP 
COLOR routine. LOOKUP COLOR uses the specified color map to find out 
the values with respect to a specific screen. It returns both the exact RGB 
values and the closest RGB values supported by hardware. 
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Drawing Graphics 


Xlib provides clients with routines that draw graphics into windows and 
pixmaps. This chapter describes how to create and manage graphics 
drawn into windows, including the following topics: 


¢ Drawing points, lines, rectangles, and arcs 

e Filling rectangles, polygons, and arcs 

¢ Copying graphics 

¢ Limiting graphics to a region of a window or pixmap 
¢ Clearing graphics from a window 


¢ Creating cursors 


Chapter 7 describes drawing graphics into pixmaps. 





Graphics Coordinates 


Xlib graphics coordinates define the position of graphics drawn in a 
window or pixmap. Coordinates are either relative to the origin of the 
window or pixmap in which the graphics object is drawn or relative to a 
previously drawn graphics object. 


Xlib graphics coordinates are similar to the coordinates that define window 
position. Xlib measures length along the x axis from the origin to the 
right. Xlib measures length along the y axis from the origin down. Xlib 
specifies coordinates in units of pixels. 


Using Graphics Routines Efficiently 


If clients use the same drawable and graphics context for each call, 

Xlib handles back to back calls of DRAW POINT, DRAW LINE, DRAW 
SEGMENT, DRAW RECTANGLE, FILL ARC, and FILL RECTANGLE in 
a batch. Batching increases efficiency by reducing the number of requests 
to the server. . 


When drawing more than a single point, line, rectangle, or arc, clients 
can also increase efficiency by using routines that draw or fill multiple 
graphics (DRAW POINTS, DRAW LINES, DRAW SEGMENTS, DRAW 
RECTANGLES, DRAW ARCS, FILL ARCS, and FILL RECTANGLES). 
Clipping negatively affects efficiency. Consequently, clients should ensure 
that graphics they draw to a window or pixmap are within the boundary 
of the drawable. Drawing outside the window or pixmap decreases 
performance. Clients should also ensure that windows into which they 
are drawing graphics are not occluded. 
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The most efficient method for clearing multiple areas is using the FILL 
RECTANGLES routine. By using the FILL RECTANGLES routine, clients 
can increase server performance. For information about using FILL 
RECTANGLES to clear areas, see Section 6.6.1. 





Drawing Points and Lines 


Drawing Points 


Xlib includes routines that draw points and lines. When clients draw 
more than one point or line, performance is most efficient if they use Xlib 
routines that draw multiple points or lines rather than calling single point 
and line-drawing routines many times. 


This section describes using routines that draw both single and multiple 
points and lines. 


To draw a single point, use the DRAW POINT routine, specifying x and y 
coordinates, as in the following: 


PARAMETER X = 100, Y = 100 


CALL XSDRAW_POINT(DPY, WINDOW, GC, X, Y) 
If drawing more than one point, use the following method: 
1 Define an array of point data structures. 


2 Call the DRAW POINTS routine, specifying the array that defines the 
points, the number of points the server is to draw, and the coordinate 
system the server is to use. The server draws the points in the order 
specified by the array. 


Xlib includes the point data structure to,enable clients to define an array 
of points easily. Figure 6-1 illustrates the data structure. 


Figure 6-1 Point Data Structure 
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Table 6-1 describes the members of the data structure. 


Table 6-1 Point Data Structure Members 


Member Name Contents 
X$W_GPNT_X Defines the x value of the coordinate of a point 
X$W_GPNT_Y Defines the y value of the coordinate of a point 
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The server determines the location of points according to the following: 


¢ If the client specifies the constant x$c_coord_mode_origin, the 
server defines all points in the array relative to the origin of the 
drawable. 


e Ifthe client specifies the constant x$c_coord_mode_previous, the 
server defines the coordinates of the first point in the array relative 
to the origin of the drawable and the coordinates of each subsequent 
point relative to the point preceding it in the array. 


The server refers to the following members of the GC data structure to 
define the characteristics of points it draws: 


Function Plane mask 
Foreground Subwindow mode 
Clip x origin Clip y origin 

Clip mask 


Chapter 4 describes GC data structure members. 


Example 6—1 uses the DRAW POINTS routine to draw a circle of points 
each time the user clicks MB1. 


Figure 6—2 illustrates sample output from the program. 


Example 6-1 Drawing Multiple Points 


aqaagaaAaAnAAN 


Create window WINDOW on display DPY, defined as follows: 


Position: x = 100,y = 100 
Width = 600 
Height = 600 


GC refers to the graphics context 


PARAMETER POINT CNT = 100, RADIUS = 50 


Handie events 
DO WHILE (.TRUE.) 
CALL XSNEXT_EVENT (DPY, EVENT) 


IF (EVENT. EVNT_TYPE -EQ. X$C_EXPOSE) THEN 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 


1 150, 25, ‘To create points, click MB1’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
Z 150, 50, ‘Each click creates a new circle of points’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 75, ‘To exit, click MB2’) 
END IF 


IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT. .EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN 
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Example 6—1 (Cont.) Drawing Multiple Points 


x 
Y 


EVENT.EVNT_BUTTON.X$L_BTEV_X 
EVENT.EVNT_BUTTON.X$L_BTEV_Y 


DO I = 1, POINT_CNT 
POINT _ARR(I) .X$W_GPNT_X 
POINT ARR(I) .X$W_GPNT_Y 


X + RADIUS * COS (FLOAT (TI) ) 
Y + RADIUS * SIN (FLOAT (T) ) 


END DO 
13) CALL X$DRAW_POINTS(DPY, WINDOW, GC, POINT ARR, POINT_CNT, 

1 X$C_COORD_MODE_ORIGIN) 
ENDIF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 

1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON2) THEN 

CALL SYSSEXIT (%VAL (1) ) 

END IF 

END DO 


@ After receiving notification that the server has mapped the window, 
the client writes three messages into the window. For information 
about using the DRAW IMAGE STRING routine, see Chapter 8. 


@ If the user clicks MB1, the client draws 50 points. If the user clicks 
MB2, the client exits from the system. The client determines which 
button the user clicked by referring to the button member of the 
button event data structure. For more information about the button 
event data structure, see Chapter 9. 


© The DRAW POINTS routine has the following format: 


XSDRAW_POINTS (display, drawable_id, gc_id, points, 
num_ points, point_mode) 


The point_mode argument specifies whether coordinates are relative 
to the origin of the drawable or to the previous point in the array. 
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Figure 6-2 Circles of Points Created Using the DRAW POINTS Routine 


Drawing Multiple Points 


To create points, click MB1. 
Each click creates a new circle of points. 
To exit, click MB2. 
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6.3.2. Drawing Lines and Line Segments 


Xlib includes routines that draw single lines, multiple lines, and line 
segments. To draw a single line, use the DRAW LINE routine, specifying 
beginning and ending points, as in the following: 

PARAMETER X1 = 100, Y1 = 100, 

1 X2 = 200, Y2 = 200 


CALL XS$DRAW_LINE(DISPLAY, WINDOW, GC, X1, Y1, X2, Y2) 
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To draw multiple lines, use the following method: 


1 Define an array of points using the point data structure described in 
Section 6.3.1 to specify beginning and ending line points. The server 
interprets pairs of array elements as beginning and ending points. For 
example, if the array that defines the beginning point is point|t], the 
server reads point|i + 1] as the corresponding ending point. 


2 Call the DRAW LINES routine, specifying the following: 
e The array that defines the points. 
e The number of points that define the line. 


e¢ The coordinate system the server uses to locate the points. The 
server draws the lines in the order specified by the array. 


Clients can specify either the x$c_coord_mode_origin or the x$c_ 
coord_mode_previous constant to indicate how the server determines 
the location of beginning and ending points. The server uses the methods 
described in Section 6.3.1. 


The server draws lines in the order the client has defined them in the 
point data structure. Lines join correctly at all intermediate points. If 
the first and last points coincide, the first and last line also join correctly. 
For any given line, the server draws pixels only once. The server draws 
intersecting pixels multiple times if zero-width lines intersect; it draws 
intersecting pixels of wider lines only once. 


Example 6—2 uses the DRAW LINES routine to draw a star when the 
server notifies the client that the window is mapped. 


Example 6-2 Drawing Multiple Lines 


C 
C 
C 
C 
C 


aaa 
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Create window WINDOW on display DPY, defined as follows: 


Position: x = 100,y = 100 
Width = 600 
Height = 600 


GC refers to the graphics context 


PARAMETER POINT CNT = 100, RADIUS = 50 


Handle events 
DO WHILE (.TRUE.) 


CALL X$NEXT_EVENT(DPY, EVENT) 


IF (EVENT.EVNT_ TYPE .EQ. X$C_EXPOSE) THEN 
CALL XS$DRAW_IMAGE_STRING(DPY, WINDOW, GC, 


1 150, 25, ‘To create a star, click MB1.’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 50, ’To exit, click MB2.’) 
END IF 


(continued on next page) 


Example 6—2 (Cont.) Drawing Multiple Lines 
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IF (EVENT.EVNT_ TYPE .EQ. X$C_BUTTON_PRESS 
EVENT. EVNT |_BUTTON. XSL _ BTEV | ‘BUTTON 


.XSW_GPNT_X 
POINT ARR(1). 
POINT _ARR (2) . 


1 


POINT ARR (1) 


POINT ARR (2) 
POINT ARR (3) 
POINT ARR (3) 
POINT ARR (4) 
POINT ARR (4) 
POINT ARR (5) 
POINT ARR(5) 
POINT ARR (6) 
POINT _ARR (6) 


X$W_GPNT_Y 
X$W_GPNT_X 
.XSW_GPNT Y 
.X$W_GPNT_X 
.X$W_GPNT_Y 
.X$W_GPNT X 
.XSW_GPNT_Y 
.X$W_GPNT X 
.X$W_GPNT Y 
.X$W_GPNT_X 
.X$W_GPNT_Y 


tt wot wt ut to & oe oo 


15 

500 
300 
100 
525 
500 
50 

225 
= Wee) 
225 
75 

500 


- AND. 


-EQ. X$C_BUTTON1) THEN 


CALL XSDRAW_LINES(DPY, WINDOW, GC, POINT_ARR, POINTS, 


A 


ENDIF 


X$C_COORD_MODE_ ORIGIN) 


IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 
EVENT. EVNT ' BUTTON. XSL __ BTEV BUTTON -EQ. X$C_BUTTON2) THEN 


CALL SYSS$EXIT ($VAL(1)) 


END IF 


END DO 





@ The program uses point data structures to define beginning and ending 
points of lines. 


@ The call to draw lines refers to a graphics context (GC), which the 
client has previously defined, and an array of point data structures. 
The constant x$c_coord_mode_origin indicates that all points are 
relative to the origin of WINDOW (100, 100). 


Figure 6—3 illustrates the resulting output. 


6-7 


Drawing Graphics 
6.3 Drawing Points and Lines 


Figure 6-3 Star Created Using the DRAW LINES Routine 


Drawing Multiple Lines 


To create a star, click MB1. 


To exit, click MB2. 
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Use the DRAW SEGMENTS routine to draw multiple, unconnected lines, 
defining an array of segments in the segment data structure. Figure 6—4 
illustrates the data structure. 


Figure 6-4 Segment Data Structure 





x$w_gseg_y1 x$w_gseg_x1 
x$w_gseg_y2 x$w_gseg_x2 
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Table 6-2 describes the members of the data structure. 


Table 6-2 Segment Data Structure Members 


Member Name Contents 

X$W_GSEG_X1 The x value of the coordinate that specifies one endpoint of 
the segment 

X$W_GSEG_Y1 The y value of the coordinate that specifies one endpoint of 
the segment 

X$W_GSEG_X2 The x value of the coordinate that specifies the other endpoint 
of the segment 

X$W_GSEG_Y2 The y value of the coordinate that specifies the other endpoint 


of the segment 


DRAW SEGMENTS functions like the DRAW LINES routine, except the 
routine does not use the coordinate mode. 


The DRAW LINE and DRAW SEGMENTS routines refer to all but the join 
style, fill rule, arc mode, and font members of the GC data structure to 
define the characteristics of lines. The DRAW LINES routine refers to all 
but the fill rule, arc mode, and font members of the data structure. 


Chapter 4 describes the GC data structure. 





6.4 Drawing Rectangles and Arcs 


As with routines that draw points and lines, Xlib provides clients the 
choice of drawing either single or multiple rectangles and arcs. If a client 
is drawing more than one rectangle or arc, use the multiple-drawing 
routines for most efficiency. 


6.4.1. Drawing Rectangles 


To draw a single rectangle, use the DRAW RECTANGLE routine, 
specifying the coordinates of the upper left corner and the dimensions 
of the rectangle, as in the following: 


50, Y = 100, 
25, LENGTH = 50 


PARAMETER X 
1 WIDTH 


CALL XS$DRAW_RECTANGLE (DISPLAY, WINDOW, GC, X, Y, WIDTH, LENGTH) 


Figure 6-5 illustrates how Xlib interprets coordinate and dimension 
parameters. The z and y coordinates are relative to the origin of the 
drawable. 


6-9 


Drawing Graphics 
6.4 Drawing Rectangles and Arcs 


6-10 


Figure 6-5 Rectangle Coordinates and Dimensions 


fF 


[x, y] [x +w, y] 

h 
[x, y + h] [x + w, y + h] 
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To draw multiple rectangles, use the following method: 
1 Define an array of rectangles using the rectangle data structure. 


2 Call the DRAW RECTANGLES routine, specifying the array that 
defines rectangle origin, width, and height, and the number of array 
elements. 


The server draws each rectangle as shown in Figure 6-6. 


Figure 6-6 Rectangle Drawing 


Path of lines drawn 
Bg Tt 5 gs 


IX 3» 3) ¢—AHAAN i —_____________— Ko, Yo] 
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For a specified rectangle, the server draws each pixel only once. If 
rectangles intersect, the server draws intersecting pixels multiple times. 


Xlib includes the rectangle data structure to enable clients to define an 
array of rectangles easily. Figure 6—7 illustrates the data structure. 


Figure 6-7 Rectangle Data Structure 






; 
x$w_grec_height x$w_grec_width 4 





Table 6-3 describes the members of the data structure. 


Table 6-3 Rectangle Data Structure Members 


Member Name Contents 

X$W_GREC_X Defines the x value of the rectangle origin 
X$W_GREC_Y Defines the y value of the rectangle origin 
X$W_GREC_WIDTH Defines the width of the rectangle 
X$W_GREC_HEIGHT Defines the height of the rectangle 


When drawing either single or multiple rectangles, the server refers 
to the following members of the GC data structure to define rectangle 


characteristics: 

Function Plane mask 
Foreground Background 

Line width Line style 

Join style Fill style 

Tile Stipple 

Tile/stipple x origin Tile/stipple y origin 
Subwindow mode Clip x origin 

Clip y origin Clip mask 

Dash offset Dashes 


Chapter 4 describes the GC data structure members. 


Example 6-3 illustrates using the DRAW RECTANGLES routine. 
Figure 6—8 shows the resulting output. 


6-11 


Drawing Graphics | 
6.4 Drawing Rectangles and Arcs 


Example 6-3 Drawing Multiple Rectangles 





Cc Create window WINDOW on display DPY, defined as follows: 
C Position: x = 100,y = 100 

c Width = 600 

c Height = 600 

Cc GC refers to the graphics context 


PARAMETER -POINT_ CNT = 100, RADIUS = 50 


Handle events 


aaa 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT (DPY, EVENT) 


@ IF (EVENT.EVNT TYPE EQ. X$C_EXPOSE) THEN 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 25, ‘To draw multiple rectangles, click MB1.’) 
CALL XS$DRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 50, ‘To exit, click MB2.’) 
END IF 


@ IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
i, EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN 


DO I = 1, REC_CNT 
REC_ARR(I) .X$W_GREC_X = STEP * I 
REC_ARR(I).X$W_GREC Y = STEP * I 
REC_ARR(I).X$W_GREC_ WIDTH = STEP * 2 
REC_ARR(I) .X$W_GREC_ HEIGHT = STEP * 3 

END DO 


© CALL X$DRAW_RECTANGLES (DPY, WINDOW, GC, REC_ARR, REC CNT) 
ENDIF 


IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT.EVNT_BUTTON.XS$L_BTEV_ BUTTON .EQ. X$C_BUTTON2) THEN 
CALL SYSSEXIT(%VAL (1) ) 


END IF 
END DO 





@ After receiving notification that the server has mapped the window, 
the client writes two messages into the window. For information about 
using the DRAW IMAGE STRING routine, see Chapter 8. 


@ If the user clicks MB1, the client draws rectangles defined in the 
initialization loop. If the user clicks MB2, the client exits the system. 
The client determines which button the user has clicked by referring 
to the button member of the button event data structure. For more 
information about the button event data structure, see Chapter 9. 


© The DRAW RECTANGLE routine has the following format: 


XS$DRAW_RECTANGLES (display, drawable_id, gc_id, rectangles, 
num_rectangles) 
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Figure 6-8 Rectangles Drawn Using the DRAW RECTANGLES Routine 


DT e=\ i tale M\Lelid) olism nicreat-larep (crs) 


To draw multiple rectangles, click MB1. 


To exit, click MB2. 
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6.4.2 Drawing Arcs 


Xlib routines enable clients to draw either single or multiple arcs. To 
draw a single arc, use the DRAW ARC routine, specifying a rectangle that 
defines the boundaries of the arc and two angles that determine the start 
and extent of the arc, as in the following: 


PARAMETER X 50, Y = 100, 
id WIDTH 25, LENGTH = 50, 
1 ANGLE1 = 5760, ANGLE2 = 5760 


CALL X$DRAW_ARC(DISPLAY, WINDOW, GC, X, Y, WIDTH, HEIGHT, 
1 ANGLE1, ANGLE2) 
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The server draws an arc within a rectangle. The client specifies the upper 


left corner of the rectangle, relative to the origin of the drawable. The 
center of the rectangle is the center of the arc. The width and height of 
the rectangle are the major and minor axes of the arc, respectively. 


Two angles specify the start and extent of the arc. The angles are signed 
integers in degrees scaled up by 64. For example, a client would specify a 
90 degree arc as 64% 90 or 5760. The start of the arc is specified by the first: 
angle, relative to the three o’clock position from the center of the rectangle. 
The extent of the arc is specified by the second angle, relative to the start 
of the arc. Positive integers indicate counterclockwise motion; negative 
integers indicate clockwise motion. 


Figure 6-9 illustrates the relationships among the rectangle, axes, and 
angles that specify the arc. 


Figure 6-9 Specifying an Arc 





Angle 2: 
Relative to 
X-Y Angle 1 
Coordinate 
‘a a Angle 1: 
Relative to Three 
O'clock Position 
Height Three O’clock 
Position 
Width 
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For an arc specified as [ 2, y, width, height, angle1, angle2], the origin of the 
major and minor axes is at [ 2+ width/2, y + hetght/2]. The infinitely 
thin path describing the entire arc intersects the horizontal axis at 

[ ty + height/2] and [ 2+ width, y + hetght/2] and the vertical axis at 
[2+ width/2, y] and [ «+ width/2, y+ height]. These coordinates are not 
truncated to discrete coordinates if they are fractional. 


The path of the arc is defined as the ideal mathematical path. For a wide 
line of width w, the bounding outlines for filling are given by two infinitely 
thin paths consisting of all points whose perpendicular distance from the 
path of the circle or ellipse is equal to w/2. 
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For an ellipse defined as [ a, y, width, height, angle1, angle2], the angles 
must be specified in the skewed coordinate of the ellipse. The relationship 
between the coordinate system of the ellipse and that of a circle is specified 
using the following formula: 


skewed angle = atan(tan(normal angle) * width/height) + adjust 


The skewed angle and normal angle are expressed in radians (rather than 
in degrees scaled by 64) in the range [ 0, 2 * x], where the atan returns a 
value in the range [ —1/2, 1/2]. The adjust is as follows: 


¢ 0 for normal-angle in the range [ 0, 1/2] 
¢ «for a normal angle in the range [ 1/2, 3 * 7/2] 


¢ 2a for a normal angle in the range [ 3 « 1/2, 2* 7] 


To draw multiple arcs, use the following method: 
1. Define an array of are data structures. 


2 Call the DRAW ARCS routine, specifying the array that defines the 
arcs and the number of array elements. 


Figure 6-10 illustrates the arc data structure. 
Figure 6-10 Arc Data Structure 












: 
x$w_garc_height x$w_garc_width 4 
x$w_garc_angle2 x$w_garc_angle1 8 

Table 6—4 describes the members of the arc data structure. 

Table 6-4 Arc Data Structure Members 

Member Name Contents 

X$W_GARC_X Defines the x-coordinate value of the rectangle in which 
the server draws the arc 

X$W_GARC_Y Defines the y-coordinate value of the rectangle in which 
the server draws the arc 

X$W_GARC_WIDTH Defines the major axis of the arc 

X$W_GARC_HEIGHT Defines the minor axis of the arc 


(continued on next page) 
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Table 6—4 (Cont.) Arc Data Structure Members 


Member Name Contents 

X$W_GARC_ANGLE1 Defines the starting point of the arc relative to the 
3-o’clock position from the center of the rectangle 

X$W_GARC_ANGLE2 Defines the extent of the arc relative to the starting point 


When drawing either single or multiple arcs, the server refers to the 
following members of the GC data structure to define arc characteristics: 


Function Plane mask 
Foreground Background 

Line width Line style 

Join style Cap style 

Fill style ‘Tile 

Tile/stipple x origin | Tile/stipple y origin 
Clip x origin Clip y origin 

Clip mask Dash offset 
Dashes Stipple 


Subwindow mode 
Chapter 4 describes the GC data structure members. 


If the last point in one arc coincides with the first point in the following 
arc, the two arcs join. If the first point in the first arc coincides with the 
last point in the last arc, the two arcs join. 


If two arcs join, the line width is greater than zero, and the arcs intersect, 
the server draws all pixels only once. Otherwise, it may draw intersecting 


pixels multiple times. 


Example 6—4 illustrates using the DRAW ARCS routine. 


Example 6-4 Drawing Multiple Arcs 


Create window WINDOW on display DPY, defined as follows: 


Cc 

C Position: x = 100,y = 100 

Cc Width = 600 

Cc Height = 600 

Cc GC refers to the graphics context 


PARAMETER ARC_CNT = 16, RADIUS = 50, 


1 INNER_RADIUS = 20 


Handle events 


aan 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT(DPY, EVENT) 
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Example 6—4 (Cont.) Drawing Multiple Arcs 





IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 


1 150, 25, '’To create arcs, click MB1.’) 
CALL XS$DRAW_IMAGE STRING(DPY, WINDOW, GC, 
1 150, 50, ‘Each click creates a new circle of arcs.’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
pi 150, 75, ‘To exit, click MB2.’) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_ BUTTON -EQ. X$C_BUTTON1) THEN 
St] X = EVENT.EVNT_BUTTON.X$L_BTEV_X 
Y = EVENT.EVNT BUTTON.X$L_BTEV_Y 
DO I = 1, ARC_CNT 
ARC_ARR(I) .X$W_GARC_ANGLE1 = (64 * 360) /ARC_CNT * T 
ARC_ARR(I) .X$W_GARC_ANGLE2 = (64 * 360) /ARC_CNT * 3 
ARC_ARR(I) .X$W_GARC_WIDTH = RADIUS * 2 
ARC_ARR(I) .X$W_GARC_HEIGHT = RADIUS * 2 
ARC_ARR(I).X$W_GARC_X = X - RADIUS + 
1 SIN (2*3.14159/ARC_CNT*TI) * INNER_RADIUS 
ARC_ARR(I) .X$W_GARC_Y = Y - RADIUS + 
1 COS (2*3.14159/ARC_CNT*I) * INNER_RADIUS 
END DO 
@ CALL XSDRAW_ARCS (DPY, WINDOW, GC, ARC_ARR, ARC_CNT) 
ENDIF 
IF (EVENT.EVNT_ TYPE .EQ. X$C_BUTTON_PRESS -AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON -EQ. X$C_BUTTONZ2) THEN 
CALL SYSSEXIT(%$VAL (1) ) 
END IF 
END DO 





@ The «x and y variables specify the upper left corner of the rectangle that 
defines the boundary of the arc. The client determines the rectangle 
coordinates by taking the values of the x and y arguments from the 
button event data structure. Because these values indicate the position 
of the cursor when the user clicks the mouse button, the server draws 
the arcs relative to the position of the cursor. For more information 
about the button event data structure, see Chapter 9. 


@ The DRAW ARCS routine has the following format: 


XS$DRAW_ARCS (display, drawable_id,gc_id,arcs,num_arcs) 


Figure 6—11 illustrates the resulting output. 
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Figure 6-11 Multiple Arcs Drawn Using the DRAW ARCS Routine 


Drawing Multiple Arcs 


To create arcs, click MB1. 
Each click creates a new circle of arcs. 
To exit, click MB2. 
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6.5 Filling Areas 


This section describes using Xlib routines to fill single rectangles, arcs, 
and polygons, and multiple rectangles and arcs. 


6.5.1. ‘Filling Rectangles and Arcs 


The FILL RECTANGLE, FILL RECTANGLES, FILL ARC, and FILL 
ARCS routines create single and multiple rectangles or arcs and fill them 
using the fill style the client specifies in a graphics context data structure. 


The method of calling the fill routines is identical to that for drawing 
rectangles and arcs. For example, to create rectangles filled solidly with 
foreground color in Example 6-3, the client needs only to call the FILL 
RECTANGLES routine instead of DRAW RECTANGLES. The default 
value of the GC data structure fill style member is solid. If the client were 
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to specify a tile or stipple for filling the rectangles, the client would have 
to change the graphics context used by the FILL RECTANGLES routine. 


The server refers to the following members of the GC data structure to 
define characteristics of the rectangles and arcs it fills: 


Function Plane mask 
Foreground Background 

Fill style . Tile 

Stipple Subwindow mode 
Tile/stipple x origin Tile/stipple y origin 
Clip x origin Clip y origin 

Clip mask | 


Additionally, the server refers to the arc mode member if filling arcs. 


For information about using graphics context, see Chapter 4. 


6.5.2 ‘Filling a Polygon | 
To fill a polygon, use the following method: 
1 Define an array of point data structures. 


2 Call the FILL POLYGON routine, specifying the array that defines the 
points of the polygon, the number of points the server is to draw, the 
shape of the polygon, and the coordinate system the server is to use. 
The server draws the points in the order specified by the array. 


See Figure 6—1 for an illustration of the point data structure. 


To improve performance, clients can specify whether the shape of the 
polygon is complex, convex, or nonconvex, as follows: 


¢ Specify the constant x$c_complex as the shape argument if the path 
that draws the polygon may intersect itself. 


e Specify the constant x$c_convex if the path that draws the shape is 
wholly convex. If a client specifies x$c_convex for a path that is not 
convex, the results are undefined. 


¢ Specify the constant x$c_nonconvex as the shape argument if the 
- path does not intersect itself, but the shape is not wholly convex. Ifa 
client specifies x$c_nonconvex for a path that intersects itself, the 
results are undefined. 


When filling the polygon, the server draws each pixel only once. 
The server determines the location of points as follows: 


¢ If the client specifies the constant x$c_coord_mode_origin, the 
server defines all points in the array relative to the origin of the 
drawable. 
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Example 6-5 Filling a Polygon 


¢ Ifthe client specifies the constant x$c_coord_mode_previous, the 
server defines the coordinates of the first point in the array relative 
to the origin of the drawable and the coordinates of each subsequent 
point relative to the point preceding it in the array. 


If the last point does not coincide with the first point, the server closes the 


polygon automatically. 


The server refers to the following members of the GC data structure to 
define the characteristics of the polygon it fills: 


Function 


Foreground 


Fill rule (if polygon is complex) 
Tile/stipple x origin 


Clip x origin 
Subwindow mode 


Stipple 


Plane mask 

Fill style 

Tile 

Tile/stipple y origin 
Clip y origin 

Clip mask 
Background 


Chapter 4 describes GC data structure members. 
Example 6—5 uses the FILL POLYGON routine to draw and fill the star 


created in Example 6-2. 





+) aAaaRAaAANAAN 


aaa 
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Height 


600 
600 


100 


GC refers to the graphics context 


RECORD /X$POINT/ PT_ARR(6) 


PT _ARR(1) 
PT ARR(1) 
PT ARR (2) 
PT ARR (2) 
PT ARR (3) 
PT ARR (3) 
PT ARR (4) 
PT ARR (4) 
PT ARR(5) 
PT _ARR (5) 
PT ARR (6) 
PT ARR (6) 


.X$W_GPNT_X 
.X$W_GPNT_Y 
.XSW_GPNT_X 
.X$W_GPNT_Y 
.X$W_GPNT_X 
.X$W_GPNT_Y 
.X$W_GPNT_X 
.X$W_GPNT_Y 
.X$W_GPNT_X 
.X$W_GPNT_Y 


.X$W_GPNT_X 


.X$W_GPNT_Y 


Handle events 


DO WHILE (.TRUE.) 


CALL X$NEXT_EVENT(DPY, EVENT) 
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Create window WINDOW on display DPY, defined as follows: 
Position: x = 100,y 
Width = 
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Example 6—5 (Cont.) Filling a Polygon 


IF (EVENT.EVNT TYPE .EQ. X$C_EXPOSE) THEN 
CALL X$DRAW_IMAGE STRING (DPY, WINDOW, GC, 


1 150, 25, 'To create a filled polygon, click MB1’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 

i: 150, 50, ‘To exit, click MB2’) 

END IF 
@ IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON PRESS .AND. 

1 EVENT.EVNT BUTTON.X$L_BTEV_BUTTON -EQ. X$C_BUTTON1) THEN 
CALL XSFILL_ POLYGON (DPY, WINDOW, GC, PT_ARR, 6, X$C_COMPLEX, 

i X$C_COORD_MODE_ORIGIN) 
ENDIF 


@ Use an array of point data structures to specify the points that define 
the polygon. 


@ The call to fill the polygon refers to a graphics context (GC), which the 
client has previously defined, and an array of point data structures. 
The constant x$c_complex indicates that the path of the line that 
draws the polygon intersects itself. The constant x$c_coord_mode_ 
origin indicates that all points are relative to the origin of WINDOW 
(100,100). 


Figure 6-12 illustrates the resulting output. 
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Figure 6-12 Filled Star Created Using the FILL POLYGON Routine 


Filling a Polygon 


To create a filled polygon, click MB1. 


To exit, click MB2. 
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6.6 Clearing and Copying Areas 


Xlib includes routines that enable clients to clear or copy a specified area 
of a drawable. Because pixmaps do not have defined backgrounds, clients 
clearing an area of a pixmap must use the FILL RECTANGLE routine 
described in Section 6.5.1. For more information about pixmaps, see 
Chapter 7. 


This section describes how to clear windows and copy areas of windows 
and pixmaps. 
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6.6.1. Clearing Window Areas 


To clear an area of a window, use the CLEAR AREA or CLEAR WINDOW 
routine. The CLEAR AREA routine clears a specified area and generates 
an exposure event, if the client directs the server to do so. 


The CLEAR WINDOW routine clears the entire area of the specified 
window. If the window has a defined background tile, the window is 
retiled. If the window has no defined background, the server does not 
change the window contents. 


Example 6-6 illustrates clearing a window. 


Example 6-6 Clearing a Window 


IF (EVENT.EVNT_ TYPE .EQ. XSC_BUTTON PRESS .AND. 


1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN 
X = EVENT.EVNT BUTTON.X$L_BTEV_X 
Y = EVENT.EVNT BUTTON.XS$L BTEV_Y 
DO I = 1, ARC_CNT 
ARC_ARR(I) .X$W_GARC_ANGLE1 = (64 * 360)/ARC_CNT * I 
ARC_ARR(I).X$W_GARC_ANGLE2 = (64 * 360)/ARC_CNT * 3 
ARC_ARR(I) .X$W_GARC WIDTH = RADIUS * 2 
ARC_ARR(I) .X$W_GARC HEIGHT = RADIUS * 2 
ARC_ARR(I).X$W_GARC_X = X - RADIUS + 
1 SIN(2*3.14159/ARC_CNT*I) * INNER_RADIUS 
ARC_ARR(I) .X$W_GARC_Y = Y - RADIUS + 
1 COS (2*3.14159/ARC_CNT*I) * INNER_RADIUS 
END DO ~ 
CALL X$DRAW_ARCS(DPY, WINDOW, GC, ARC_ARR, ARC_CNT) 
ENDIF 
IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON_PRESS .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_ BUTTON .EQ. X$C_BUTTON2) THEN 


CALL SYSSEXIT(%VAL (1) ) 


END IF 


IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 
1 EVENT.EVNT BUTTON.X$L_BTEV BUTTON .EQ. X$C_BUTTON3) THEN 
CALL X$CLEAR_WINDOW(DPY, WINDOW) 


END IF 
END DO 


The example modifies Example 6—4 to clear the window when the user 
clicks MB3. 


If clearing multiple areas, using the FILL RECTANGLES routine is faster 
than using the CLEAR WINDOW or CLEAR AREA routine. To clear 
multiple areas on a monochrome screen, first set the function member 

of the GC data structure to the value specified by the constant X$C_ 
GX_CLEAR. Then call the FILL RECTANGLES routine. If the screen 

is a color type, set the value of the background to the background of the 
window before calling FILL RECTANGLES. 
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6.6.2 Copying Areas of Windows and Pixmaps | 


Xlib includes the COPY AREA and COPY PLANE routines to enable 
clients to copy a rectangular area defined on one window or pixmap (the 
source) to an area of another window or pixmap (the destination). COPY 
AREA copies areas between drawables of the same root and depth. COPY 
PLANE copies a single bit plane of the specified drawable to another 
drawable, regardless of their depths. The bit plane is treated as a stipple 
with a fill style of x$c_fill_opaque_stippled. Both drawables must have 
the same root window. 


The server refers to the following members of the GC data structure when 
copying areas and planes: 


Function Plane mask 
Clip x origin Clip y origin 
Subwindow mode Clip mask 


Graphics exposures 


If the client calls COPY AREA or COPY PLANE, the server also refers to 
the graphics exposures member of the GC data structure. If the client calls 
the COPY PLANE routine, the server additionally refers to the foreground 
and background members. 





6.7 Defining Regions 


A region is an arbitrarily defined area within which graphics drawing is 
clipped. In other words, clipping regions are portions of either windows or 
pixmaps in which clients can restrict output. As Chapter 4 notes, the SET 


_CLIP MASK, SET CLIP ORIGIN, and SET CLIP RECTANGLES routines 


define clipping regions. Xlib provides other, more convenient, routines that 
enable clients to define regions and associate them with drawables without 
having to change graphics context values directly. 


This section describes how to create and manage clipping using Xlib region 
routines. 


6.7.1. Creating Regions 
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Xlib includes the CREATE REGION and POLYGON REGION routines for 
creating regions. CREATE REGION creates an empty region. POLYGON 
REGION creates a region defined by an array of points. 


Example 6-7 illustrates using POLYGON REGION to create a star-shaped 
region. Using the DRAW ARCS routine of Example 6-4, the program 
limits arc drawing to the star region. 


Drawing Graphics 
6.7 Defining Regions 


Example 6-7 Defining a Region Using the POLYGON REGION Routine 





Cc Create window WINDOW on display DPY, defined as follows: 
Cc Position: x = 100,y = 100 

c Width = 600 

Cc Height = 600 

Cc GC refers to the graphics context 


INTEGER*4 STAR_REGION 


PARAMETER WINDOW W = 600, WINDOW_H = 600, 
1 ARC_CNT = 16, RADIUS = 50, 
1 INNER_RADIUS = 20, NUM_POINTS = 6 


RECORD /XS$ARC/ ARC_ARR(ARC_CNT) 
RECORD /X$POINT/ POINT_ARR(NUM_POINTS) 


0 POINT_ARR(1) .XSW_GPNT_X = 75 
POINT _ARR(1).X$W_GPNT Y = 500 
POINT ARR(2).X$W_GPNT_X = 300 
POINT ARR(2).X$W_GPNT Y = 100 
POINT ARR(3) .X$W_GPNT X = 525 
POINT ARR(3).XSW_GPNT_Y = 500 
POINT ARR(4) .X$W_GPNT_X = 50 
POINT ARR(4) .X$W_GPNT_Y = 225 
POINT ARR(5).X$W_GPNT_X = 575 
POINT ARR(5).X$W_GPNT_Y = 225 
POINT _ARR(6) .X$W_GPNT_X = 75 
POINT ARR(6) .X$W_GPNT Y = 500 

e STAR_REGION = X$POLYGON_ REGION (POINT_ARR, NUM POINTS, 
i X$C_WINDING RULE) 


Handle events 


aqgaaa 


DO WHILE (.TRUE.) 
CALL XS$NEXT_EVENT (DPY, EVENT) 


IF (EVENT.EVNT_ TYPE .EQ. X$C_EXPOSE) THEN 
CALL XS$DRAW_IMAGE STRING (DPY, WINDOW, GC, 


1 150, 25, ’To create ares, click MB1.’) 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 
1 150, 50, ’Each click creates a new circle of arcs.’) 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 
1 150, 75, ’To exit, click MB2.’) 
END IF 


IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN 


Xx 
Y 


EVENT.EVNT_BUTTON.X$L_BTEV_X 
EVENT.EVNT_BUTTON.X$L_BTEV_Y 





(continued on next page) 
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Example 6-7 (Cont.) Defining a Region Using the POLYGON REGION Routine 





© CALL X$SET_REGION(DPY, GC, STAR_REGION) 
DO I = 1, ARC CNT 


ARC_ARR(I) .X$W_GARC_ANGLE1 = (64 * 360) /ARC_CNT * I 
ARC_ARR(I) .X$W_GARC_ANGLE2 = (64 * 360)/ARC_CNT * 3 
ARC_ARR(I).X$W_GARC_ WIDTH = RADIUS * 2 
ARC_ARR(I).X$W_GARC_HEIGHT = RADIUS * 2 
ARC_ARR(I).X$W_GARC X = X - RADIUS + 
1 SIN (2*3.14159/ARC_CNT*I) * INNER_RADIUS 
ARC_ARR(I) .X$W_GARC_Y = Y - RADIUS + 
1 COS (2*3.14159/ARC_CNT*I) * INNER_RADIUS 
END DO 
CALL X$DRAW_ARCS(DPY, WINDOW, GC, ARC_ARR, ARC_CNT) 
ENDIF 
IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT.EVNT BUTTON.X$L_BTEV BUTTON .EQ. X$C_BUTTON2) THEN 
CALL SYSSEXIT(%VAL(1)) 
END IF 
END DO 





@ Define an array of point data structures to define the clipping region. 


@ Define the clipping region. Note that defining the region does not 
associate it with a graphics context. 


Fill rule can be either even odd rule or winding rule. For more 
information about fill rule, see Chapter 4. 


© Associate the region with a graphics context. The association sets 
fields in the specified GC data structure that control clipping. 
Drawables that refer to the GC data structure have output clipped 
to the region. 


Figure 6—13 illustrates sample output from the program. 
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Figure 6-13 Arcs Drawn Within a Region 


Drawing Multiple Arcs in a Region 


To create arcs, click MB1. 
Each click creates a new circle of arcs. 
To exit, click MB2. 
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6.7.2 Managing Regions 
Xlib includes routines that enable clients to do the following: 
¢ Move and shrink a region 
¢ Compute the intersection, union, and results of two regions 
e Determine if regions are empty or equal 


¢ Locate a point or rectangle within a region 


Table 6—5 lists and describes Xlib routines that manage regions. 
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Table 6-5 Routines for Managing Regions 





Routine Description 

Moving and Shrinking 

OFFSET REGION Moves a region a specified amount 

SHRINK REGION Reduces a region a specified amount 
Computing 

INTERSECT REGION Computes the intersection of two regions 
UNION REGION Computes the union of two regions 

SUBTRACT REGION Subtracts two regions 

XOR REGION Calculates the difference between the union and 


intersection of two regions 


Determining if Regions are Empty or Equal 


EMPTY REGION . Determines if a region is empty 
EQUAL REGION Determines if two regions have the same offset, size, 
. and shape 





Locating a Point or Rectangle Within a Region 





POINT IN REGION Determines if a point is within a region 


RECT IN REGION Determines if a rectangle is within a region 





Example 6-8 illustrates creating a region from the intersection of two 
others. 


Example 6-8 Defining the Intersection of Two Regions 





agaaAaaAanNnAN 


Create window WINDOW on display DPY, defined as 


follows: 


Position: 
Width = 600 
600 


Height 


x 


= 100,y = 100 


GC refers to the graphics context 


INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 


PIXMAP_1 
PIXMAP 2 
PIXMAP 3 
REGION_1 
REGION 2 
REGION_3 


RECORD /X$POINT/ PT_ARR1 (4) 
RECORD /X$POINT/ PT_ARR2 (4) 
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Example 6-8 (Cont.) Defining the Intersection of Two Regions 





aaa 


@ceco 


PT_ARRI1 (1) 
PT ARR1 (1) 
PT _ARR1 (2) 
PT_ARR1 (2) 
PT_ARR1 (3) 
PT_ARR1 (3) 
PT ARRI1 (4) 
PT _ARR1 (4) 


PT_ARR2 (1) 
PT ARR2 (1) 
PT ARR2 (2) 
PT ARR2 (2) 
PT ARR2 (3) 
PT ARR2 (3) 
PT ARR2 (4) 
PT _ARR2 (4) 


Initialize 


I= 0 


PIXMAP 1 = 
PIXMAP 2 
PIXMAP 3 = 


CALL 
1 
CALL 
1 
CALL 
1 


CALL 
1 


CALL 
CALL 
CALL 
CALL 


Create the 


REGION 1 
REGION 2 


tl 


.XS$W_GPNT_X 
.X$W_GPNT_Y 
.-X$W_GPNT_X 
.X$W_GPNT_Y 
.X$W_GPNT_X 
.X$W_GPNT_Y 
.X$W_GPNT_X 
-X$W_GPNT_Y 


.X$W_GPNT_X 
.X$W_GPNT_Y 
.X$W_GPNT_X 
.X$W_GPNT_Y 
.X$W_GPNT_X 
.X$W_GPNT_Y 
.X$W_GPNT_X 
.X$W_GPNT_Y 


the counter 


Create pixmaps for tiling 


= 200 
100 
50 
300 
200 
500 
350 
300 


400 
= 100 
250 
300 
400 
500 
550 
= 300 


ll 


for mapping regions 


X$CREATE PIXMAP (DPY, WINDOW, PIX_WIDTH, PIX_HEIGHT, DEPTH) 
XSCREATE_PIXMAP (DPY, WINDOW, PIX_WIDTH, PIX_HEIGHT, DEPTH) 
XSCREATE PIXMAP(DPY, WINDOW, PIX_WIDTH,. PIX_HEIGHT, DEPTH) 


PIX HEIGHT) 


PIX HEIGHT) 


X$FILL_ RECTANGLE (DPY, 


PIX HEIGHT) 


XSDRAW_LINE (DPY, 
X$DRAW LINE (DPY, 
XSDRAW_LINE (DPY, 
XSDRAW_LINE (DPY, 


regions 


2)) 


PIXMAP 1, 
PIXMAP 2, 
PIXMAP_ 3, 
PIXMAP 3, 


GC, 
GC, 
GC, 
GC, 


i i 


oO fF O fb 


St 


aowve 


XSFPILL_RECTANGLE (DPY, PIXMAP_1, GC, 0, 0, PIX_WIDTH, 
XSFILL RECTANGLE (DPY, PIXMAP_2, GC, O, O, PIX_WIDTH, 
PIXMAP_ 3, GC, 0, 0, PIX_WIDTH, 


X$SET_ FOREGROUND (DPY, GC, DEFINE _COLOR(DPY, SCREEN, 
VISUAL, 


XSPOLYGON_REGION (PT_ARR1, 4, X$C_WINDING_ RULE) 
XSPOLYGON_REGION(PT_ARR2, 4, X$C_WINDING RULE) 


Handle events 


DO WHILE ( 


- TRUE.) 
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Example 6-8 (Cont.) Defining the Intersection of Two Regions 





CALL X$NEXT_EVENT(DPY, EVENT) 


IF (EVENT.EVNT TYPE .EQ. X$C_EXPOSE) THEN 
CALL X$DRAW_IMAGE_ STRING (DPY, WINDOW, GC, 


1 150, 25, ’'To map regions click MBl1 three times.’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 75, 'To exit, click MB2’) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT .EVNT_BUTTON.X$L_BTEV_BUTTON -EQ. X$C_BUTTON1) THEN 
I=TI+i1 


IF (I .EQ. 1) THEN 

© CALL X$SET_FILL STYLE(DPY, GC, X$C_FILL_ TILED) 
CALL X$CLEAR_WINDOW(DPY, WINDOW) 
CALL X$SET_TILE(DPY, GC, PIXMAP_1) 


4) CALL X$SET_REGION(DPY, GC, REGION_1) 
5 CALL X$FPILL RECTANGLE (DPY, WINDOW, GC, X_ORIGIN, 
1 Y ORIGIN, WINDOW _W, WINDOW_H) 
END IF 
IF (I .EQ. 2) THEN 
6) CALL XS$CLEAR_WINDOW(DPY, WINDOW) 
CALL X$SET_TILE(DPY, GC, PIXMAP 2) 
CALL XSSET_REGION(DPY, GC, REGION 2) 
CALL X$FILL_RECTANGLE(DPY, WINDOW, GC, X_ORIGIN, 
1 Y ORIGIN, WINDOW W, WINDOW _H) 
END IF 
IF (I .EQ. 3) THEN 
CALL X$CLEAR_WINDOW(DPY, WINDOW) 
7) REGION 3 = X$CREATE_REGION( ) 
CALL X$INTERSECT REGION(REGION 1, REGION 2, 
i REGION_3) 
CALL X$SET_TILE(DPY, GC, PIXMAP_3) 
CALL X$SET_REGION(DPY, GC, REGION 3) 
CALL X$FILL_RECTANGLE(DPY, WINDOW, GC, X_ORIGIN, 
1 Y ORIGIN, WINDOW _W, WINDOW _H) 
END IF 
IF (I .GT. 3) THEN 
8) CALL X$SET_ FILL STYLE(DPY, GC, X$C_FILL_ SOLID) 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 
1 150, 75, ‘That’’s it! Click MB2 to exit.’) 
END IF 
END IF 





@ Arrays of point data structures define two regions. 


© The pixmaps are used to tile the window with horizontal, vertical, and 
cross-hatched lines. For information about pixmaps, see Chapter 7. 


© After writing messages in the window, the fill style defined in the 
GC data structure is changed to tile the window with pixmaps. The 
subsequent call to SET TILE defines one of the three pixmaps created 
earlier as the window background pixmap. For information about fill 
styles and tiling, see Chapter 4. 
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@ The SET REGION routine specifies the clipping region in the graphics 


context. The region defined by PT_ARR1 is first specified. 


FILL RECTANGLE repaints the window, filling it with the tiling 
pattern defined in PIXMAP_1. Tiling is restricted to the region defined 
by REGION_1. 


Before specifying a new tiling pattern and region, the window is 
cleared. 


CREATE REGION creates an empty region and returns an identifier, 
REGION_3. Xlib returns the results of intersecting REGION_1 and 
REGION_2 to REGION_3. 


Before displaying a final message in the window, the fill style is 
redefined to solid to enable text writing. 


Figure 6—14 illustrates the output from the program. 


Figure 6-14 Intersection of Two Regions 


Intersection of Two Regions 
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6.8 Defining Cursors 


A cursor is a bit image on the screen that indicates either the movement 
of a pointing device or the place where text will next appear. Xlib enables 
clients to associate a cursor with each window they create. After making 
the association between cursor and window, the cursor is visible whenever 
it is in the window. If the cursor indicates movement of a pointing device, 
the movement of the cursor in the window automatically reflects the 
movement of the device. 


Xlib and VMS DECwindows provide fonts of predefined cursors. Clients 
that want to create their own cursors can either define a font of shapes 
and masks or create cursors using pixmaps. 


This section describes the following: 


¢ Creating cursors using the Xlib cursor font, a font of shapes and 
masks, and pixmaps 


e Associating cursors with windows 
¢ Managing cursors 


¢ Freeing memory allocated to cursors when clients no longer need them 


6.8.1 Creating Cursors 


Xlib enables clients to use predefined cursors or to create 

their own cursors. To create a predefined Xlib cursor, use the 
CREATE FONT CURSOR routine. Xlib cursors are predefined in 
SYS$LIBRARY:DECW$XLIBDEF. Table 6-6 lists the constants that 
refer to the predefined Xlib cursors. 


Table 6-6 Predefined Xlib Cursors 


x$c_X_cursor x$c_arrow_cursor 
x$c_based_arrow_down_cursor x$c_based_arrow_up_cursor 
x$c_boat_cursor x$c_bogosity_cursor 
x$c_bottom_left_corner_cursor x$c_bottom_right_corner_cursor 
x$c_bottom_side_cursor x$c_bottom_tee_cursor 
x$c_box_spiral_cursor x$c_center_ptr_cursor 
x$c_circle_cursor x$c_clock_cursor 
x$c_coffee_mug_cursor x$c_cross_cursor 
x$c_cross_reverse_cursor x$c_crosshair_cursor 
x$c_diamond_cross_cursor x$c_dot_cursor . 
x$c_dotbox_cursor x$c_double_arrow_cursor 
x$c_draft_large_cursor x$c_draft_small_cursor 
x$c_draped_box_cursor x$c_exchange_cursor 


(continued on next page) 
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Table 6-6 (Cont.) Predefined Xlib Cursors 


x$c_fleur_cursor 
x$c_gumby_cursor 
x$c_hand2_cursor 
x$c_icon_cursor 
x$c_left_ptr_cursor 
x$c_left_tee_cursor 
x$c_ll_angle_cursor 
x$c_man_cursor 
x$c_mouse_cursor 
x$c_pirate_cursor 
x$c_question_arrow_cursor 
x$c_right_side_cursor 
x$c_rightbutton_cursor 
x$c_sailboat_cursor 
x$c_sb_h_double_arrow_cursor 
x$c_sb_right_arrow_cursor 
x$c_sb_v_double_arrow_cursor 
x$c_sizing_cursor 
x$c_spraycan_cursor 
x$c_target_cursor 
x$c_top_left_arrow_cursor 
x$c_top_right_corne_cursor 
x$c_top_tee_cursor 
x$c_ul_angle_cursor 
x$c_ur_angle_cursor 
x$c_xterm_cursor 


x$c_gobbler_cursor 
x$c_hand1_cursor 
x$c_heart_cursor 
x$c_iron_cross_cursor 
x$c_left_side_cursor 
x$c_leftbutton_cursor 
x$c_Ir_angle_cursor 
x$c_middlebutton_cursor 
x$c_pencil_cursor 
x$c_plus_cursor 
x$c_right_ptr_cursor 
x$c_right_tee_cursor 
x$c_rtl_logo_cursor 
x$c_sb_down_arrow_cursor 
x$c_sb_left_arrow_cursor 
x$c_sb_up_arrow_cursor 
x$c_shuttle_cursor 
x$c_spider_cursor 
x$c_star_cursor 
x$c_tcross_cursor 
x$c_top_left_corner_cursor 
x$c_top_side_cursor 
x$c_trek_cursor 
x$c_umbrella_cursor 
x$c_watch_cursor 


The following example creates a sailboat cursor, one of the predefined Xlib 
cursors, and associates the cursor with a window: 


INTEGER*4 FONTCURSOR 


FONTCURSOR = X$CREATE_FONT CURSOR(DPY, X$C_SAILBOAT_CURSOR) 
CALL X$DEFINE_CURSOR(DPY, WIN, FONTCURSOR) 


The DEFINE CURSOR routine makes the sailboat cursor automatically 
visible when the pointer is in window WIN. 


To create a predefined VMS DECwindows cursor, use the CREATE 
GLYPH CURSOR routine. VMS DECwindows cursors are predefined 
in SYS$LIBRARY:DECW$XLIBDEF. Table 6-7 lists the constants that 
refer to the predefined VMS DECwindows cursors. 


6-33 


Drawing Graphics 
6.8 Defining Cursors 


6-34 


Table 6-7 Predefined VMS DECwindows Cursors 





decw$c_select_cursor decw$c_leftselect_cursor 
decw$c_help_select_cursor decw$c_wait_cursor 
decw$c_inactive_cursor decw$c_resize_cursor 
decw$c_vpane_cursor decw$c_hpane_cursor 
decw$c_text_insertion_cursor decw$c_text_insertion_bl_cursor 
decw$c_cross_hair_cursor decw$c_draw_cursor 
decw$c_pencil_cursor decw$c_rpencil_cursor 
decw$c_center_cursor decw$c_rightselect_cursor 
decw$c_wselect_cursor decw$c_eselect_cursor 
decw$c_x_cursor decw$c_circle_cursor 
decw$c_mouse_cursor decw$c_lIpencil_cursor 
decw$c_leftgrab_cursor decw$c_grabhand_cursor 
decw$c_rightgrab_cursor decw$c_leftpointing_cursor 
decw$c_uppointing_cursor decw$c_rightpointing_cursor 


CREATE GLYPH CURSOR selects a cursor shape and cursor mask from 
the VMS DECwindows cursor font, defines how the cursor appears on 
the screen, and assigns a unique cursor identifier. The following example 
illustrates creating the select cursor and associating the cursor with a 
window: 


INTEGER*4 CURSOR_FONT 
INTEGER*4 GLYPHCURSOR 


RECORD/ X$COLOR/ FORE COLOR, BACK_COLOR 


CURSOR_FONT = X$LOAD_FONT(DPY, ‘DECWS$CURSOR’ ) 

CALL X$SET_FONT(DPY, GC, CURSOR_FONT) 

GLYPHCURSOR = X$CREATE_GLYPH_CURSOR(DPY, CURSOR_FONT, 

1 CURSOR_FONT, DECW$C_SELECT_CURSOR, 

1 DECWS$C_SELECT_ CURSOR + 1, FORE _COLOR, BACK_COLOR) 
CALL X$DEFINE CURSOR(DPY, WIN, GLYPHCURSOR) 


To create client-defined cursors, either create a font of cursor shapes or 
define cursors using pixmaps. In each case the cursor consists of the 
following components: 


e Shape—Defines the cursor as it appears without modification in a 
window 


¢ Mask—Acts as a clip mask to define how the cursor actually appears 
in a window 


¢ Background color—Specifies RGB values used for the cursor 
background 


¢ Foreground color—Specifies RGB values used for the cursor foreground 


¢ Hot spot—Defines the position on the cursor that reflects movements 
of the pointing device 
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Figure 6-15 illustrates the relationship between the cursor shape and the 
cursor mask. The cursor shape defines the cursor as it would appear on 
the screen without modification. The cursor mask bits that are set to 1 
select which bits of the cursor shape are actually displayed. If the mask 
bit has a value of 1, the corresponding shape bit is displayed whether it 
has a value of 1 or 0. If the mask bit has a value of 0, the corresponding 
shape bit is not displayed. 


In the resulting cursor shape, bits with a 0 value are displayed in the 
specified background color; bits with a 1 value are displayed in the 
specified foreground color. 
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Figure 6-15 Cursor Shape and Cursor Mask 
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To create a client-defined cursor from a font of glyphs, use the CREATE 
GLYPH CURSOR routine, specifying the cursor and mask fonts that 
contain the glyphs. To create a cursor from pixmaps, use the CREATE 
PIXMAP CURSOR routine. The pixmaps must have a depth of one. If the 
depth is not one, the server generates an error. 


The size of the pixmap cursor must be supported by the display on which 
the cursor is visible. To determine the supported size closest to the size 
the client specifies, use the QUERY BEST CURSOR routine. Example 6-9 
illustrates creating a pencil pointer cursor from two pixmaps. 


Example 6-9 Creating a Pixmap Cursor 





PROGRAM PIXMAP CURSOR 
INCLUDE ’SYSS$LIBRARY : DECWSXLIBDEF’ 


INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 


DPY 
SCREEN 

WINDOW 

GC_MASK 

ATTR_MASK 

GC 

FONT 

PIXMAP 

PENCIL, PENCIL MASK 
PENCIL CURSOR 

I, STATUS 

DEFINE COLOR 


INTEGER*4 WINDOW_X, WINDOW _Y, DEPTH 
LOGICAL*1 PENCIL BITS (32) 

LOGICAL*1 PENCIL MASK BITS (32) 

RECORD /X$COLOR/ COLOR_DUMMY ! used for the pixmap 
RECORD /X$COLOR/ CURSOR_FOREGROUND ! used for the pixmap 
RECORD /XSCOLOR/ CURSOR_BACKGROUND ! used for the pixmap 
RECORD /X$VISUAL/ VISUAL ! visual type 

RECORD /X$SET_WIN_ATTRIBUTES/ XSWDA ! window attributes 
RECORD /X$GC_VALUES/ XGCVL ! gc values 

RECORD /X$SIZE_HINTS/ XSZHN ! hints 

RECORD /XSEVENT/ EVENT ! input event 

PARAMETER WINDOW_W = 600, WINDOW _H = 600, 

zh PENCIL WIDTH = 16, PENCIL HEIGHT = 16, 

1 PENCIL XHOT = 1, PENCIL YHOT = 15 

DATA PENCIL BITS /’0000’X, '0070’X, ’0000’X, ’0088’X, ’0000’X, 
i ‘008C’X, ’0000’X, '0096’X, ’0000’X, '0069’X, '0080’x, 
1 0030’ X;.'0040'X, °*0010'X, *0020’xX,. *0008'X, =’ 0010" x, 
1 ‘0004’X, ’0008’X, ’0002’X, '0008’X, ’0001’X, '0094’X, 
1 ‘0000’X, '0064’X, '0000’X, ‘0O01E’X, ’0000’X, '0006'X, 
1 ‘0000’X, ’0000’X, ’0000’X/ 





(continued on next page) 
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Example 6-9 (Cont.) Creating a Pixmap Cursor 


DATA PENCIL MASK BITS /’00’X, ’F8’X, '00’X, 'FC’X, '00'X, 


- (WET X, "00'S, SEF’ X,. ’80%X,. “FE’X;, *CO’x, “TEX, 
1 TEO' Xp, “ SEtX,: "FOX, TIP, 1 Pex, YOR X, ECX, 
Bf 'O7'X, 'FC’X, '03'X, 'FE’X, '01’X, ‘'FE’X, '00’X, 
1 'TE'X, '00’X, “1F’X, '00°X, '07'X, '00°X/ 


Cc 
c Create the pixmap cursor 
Cc 
0 PIXMAP = XSCREATE_PIXMAP (DPY, X$ROOT_WINDOW_OF_ SCREEN (SCREEN) , 
L 1, 1, 1) 
2] CALL XSLOOKUP_COLOR (DPY, XSDEFAULT_COLORMAP_OF_SCREEN (SCREEN) , 
1 ‘BLACK’, COLOR_DUMMY, CURSOR_FOREGROUND) 
CALL X$SLOOKUP_COLOR (DPY, XSDEFAULT_COLORMAP_OF_SCREEN (SCREEN) , 
1 ‘WHITE’, COLOR_DUMMY, CURSOR_BACKGROUND) 
3) PENCIL = XS$CREATE PIX FROM BITMAP _DATA(DPY, PIXMAP, PENCIL BITS, 
1 PENCIL WIDTH, PENCIL HEIGHT, i, 0, 1) 
PENCIL MASK = XSCREATE PIX _FROM_BITMAP DATA(DPY, PIXMAP, 
1 PENCIL MASK BITS, PENCIL WIDTH, PENCIL HEIGHT, 1, 0, 1) 
4) PENCIL CURSOR = XSCREATE_PIXMAP_ CURSOR (DPY, PENCIL, PENCIL MASK, 


1 CURSOR_FOREGROUND, CURSOR_BACKGROUND, PENCIL XHOT, 
1 PENCIL YHOT) 
CALL X$DEFINE_CURSOR(DPY, WINDOW, PENCIL CURSOR) 





@ The client first creates a pixmap into which it will draw bit images for 
the cursor and cursor mask. Note that the depth of the pixmap must 
be one. For information about creating pixmaps, see Chapter 7. 


@ The LOOKUP COLOR routine returns the color value associated with 
the named color to the CURSOR_FOREGROUND and CURSOR_ 
BACKGROUND variables. For information about LOOKUP COLOR, 
see Chapter 5. 


© The CREATE PIXMAP FROM BITMAP DATA routine writes an image 
into a specified pixmap. The client uses the routine to write images for 
the cursor and the cursor mask into two pixmaps. 


@ The CREATE PIXMAP CURSOR routine uses the two pixmaps to 
create the pixmap cursor. 


6.8.2 Managing Cursors 


To dissociate a cursor from a window, call the UNDEFINE CURSOR 
routine. After a call to UNDEFINE CURSOR, the cursor associated with 
the parent window is used. If the window is a root window, UNDEFINE 
CURSOR restores the default cursor. UNDEFINE CURSOR does not 
destroy a cursor. Using its identifier, the client can still refer to the cursor 
and associate it with a window. 
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To change the color of a cursor, use the RECOLOR CURSOR routine. If 
the cursor is displayed on the screen, the change is immediately visible. 
For information about defining foreground and background colors, see 
Chapter 5. For information about loading fonts, see Chapter 8. 


6.8.3. Destroying Cursors 
. To destroy a cursor, use the FREE CURSOR routine. FREE CURSOR 


deletes the association between the cursor identifier and the specified 
cursor. It also frees memory allocated for the cursor. 
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7 Using Pixmaps and Images 


Xlib enables clients to create and work with both on-screen graphics, such 
as lines and cursors, and off-screen images, such as pixmaps. Chapter 4 
and Chapter 6 describe how to work with on-screen graphics objects. 


This chapter describes how to work with off-screen graphics resources, 
including the following topics: 


¢ Creating and freeing pixmaps 
e Creating and managing bitmap files 
¢ Working with images 





7.1 Creating and Freeing Pixmaps 


A pixmap is an area of memory into which clients can either define an 
image or temporarily save part of a screen. Pixmaps are useful for defining 
cursors and icons, for creating tiling patterns, and for saving portions of a 
window that has been exposed. Additionally, drawing complicated graphics 
sequences into pixmaps and then copying the pixmaps to a window is often 
faster than drawing the sequences directly to a window. 


Use the CREATE PIXMAP routine to create a pixmap. The routine creates 
a pixmap of a specified width, height, and depth. If the width or height is 
zero or the depth is not supported by the drawable root window, the server 
returns an error. The pixmap must be associated with a window, which 
can be either an input-output or an input-only window. 


Example 7-1 illustrates creating a pixmap to use as backing store for 
drawing the star of Example 6-5. 
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Example 7-1 Creating a Pixmap 





@@ocrcc aqaga aqaeganaan 


aaa 


Create window WINDOW on display DPY, defined 
as follows: 


Position: x = 100,y = 100 
Width = 600 
Height = 600 


GC refers to the graphics context 


INTEGER*4 PIXMAP 
INTEGER*4 EXPOSE FLAG 


Create graphics context 


GC_MASK = X$M_GC_FOREGROUND .OR. X$M_GC_BACKGROUND 


XGCVL.X$L_GCVL_FOREGROUND = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 3) 


XGCVL.X$L_GCVL_BACKGROUND = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 3) 


GC = XS$CREATE_GC(DPY, WINDOW, GC_MASK, XGCVL) 


Create the pixmap 


PIXMAP = X$CREATE_PIXMAP(DPY, WINDOW, WINDOW_W, WINDOW_H, DEPTH) 
CALL X$FILL RECTANGLE (DPY, PIXMAP, GC, 0, 0, WINDOW_W, 


1 WINDOW_H) 

CALL X$SET_FOREGROUND (DPY, GC, DEFINE_COLOR(DPY, SCREEN, 

1 VISUAL, 2)) 

CALL X$FILL_POLYGON(DPY, PIXMAP, GC, PT_ARR, 6, X$C_COMPLEX, 
i X$C_COORD_MODE_ORIGIN) 


Handle events 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT(DPY, EVENT) 


IF (EVENT.EVNT_ TYPE .EQ. X$C_EXPOSE) THEN 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 


1 150, 25, ‘To create a filled polygon, click MB1’) 
CALL X$DRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 75, 'To exit, click MB2’) 


IF (EXPOSE FLAG .EQ. 0) THEN 
EXPOSE FLAG = 1 


ELSE 
CALL X$COPY_AREA(DPY, PIXMAP, WINDOW, GC, 0, 0, 
1 WINDOW W, WINDOW_H, 0, 0) 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 
1 150, 75, ‘To exit, click MB2’) 
END IF 
END IF 
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Example 7-1 (Cont.) Creating a Pixmap 





END 
END 


IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON_PRESS 


EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. 


CALL XSCOPY_AREA(DPY, PIXMAP, WINDOW, 
WINDOW _W, WINDOW_H, 0, 0) 
CALL X$DRAW_IMAGE STRING (DPY, WINDOW, 
150, 75, 'To exit, click MB2’) 
ENDIF 


IF (EVENT.EVNT._ TYPE .EQ. X$C_BUTTON PRESS 


EVENT.EVNT BUTTON.X$L_BTEV_BUTTON .EQ. 


CALL SYSSEXIT(%VAL (1) ) 
END IF 
DO 


.AND. 
X$C_BUTTON1) THEN 
GC, 0, 0, 


GC, 


AND. 
X$C_BUTTON2) THEN 





@ Pixmaps use only the foreground member of the graphics context 
to define color. Because the client is using the pixmap as backing 
store, which is copied into the window to repaint exposed areas, both 
foreground and background members of the graphics context are first 
defined as the window background color. 


@ The pixmap has the width, height, and depth of the window. 


© FILL RECTANGLE fills the pixmap with the background color of the 
window. After filling the pixmap to ensure that pixel values of both 
the pixmap and window background are the same, the foreground color 
is redefined for graphics operations. 


@ After redefining foreground color, the client draws the polygon into 
the pixmap. For a description of specifying and filling the polygon, see 


Example 6-5. 


@ At the first window exposure, the client draws only the text into the 
window. On subsequent exposures, the client copies the pixmap into 
the window to repaint exposed areas. For a description of handling 


exposure events, see Chapter 9. 


Note that the CREATE PIXMAP routine is not a synchronous routine and 
does not return an error if the routine fails to create a pixmap. Although 
Xlib returns a resource id for this routine, it does not indicate that a valid 
resource was created by the server. Refer to Section 9.13.3 for a method to 
check if a pixmap, or any X resource, has been created. 


When a client no longer needs a pixmap, use the FREE PIXMAP routine to 
free storage associated with it. FREE PIXMAP first deletes the association 
between the pixmap identifier and the pixmap and then frees pixmap 


storage. 
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Creating and Managing Bitmaps 


Xlib enables clients to create files of bitmap data and then use those files 
to create either bitmaps or pixmaps. To create a bitmap data file, use the 
WRITE BITMAP FILE routine. Example 7—2 illustrates creating a pixmap 
and writing the pixmap data into a bitmap data file. 


Example 7-2 Creating a Bitmap Data File 
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PT_ARR(1).X$W_GPNT_X = 20 
PT ARR(1).X$W_GPNT Y = 0 
PT ARR(2).X$W_GPNT X = 20 
PT ARR(2).X$W_GPNT Y = 5 
PT ARR(3).X$W_GPNT X = 20 
PT ARR(3).X$W_GPNT Y = 10 
PT ARR(4).X$W_GPNT X = 20 
PT ARR(4).X$W_GPNT Y = 15 
PT_ARR(5).X$W_GPNT_X = 20 
PT_ARR(5).X$W_GPNT Y = 20 


Create the pixmap 


PIXMAP = XSCREATE_PIXMAP(DPY, WINDOW, PIX_WIDTH, PIX_HEIGHT, 
1 DEPTH) 
CALL X$FILL RECTANGLE (DPY, PIXMAP, GC, 0, 0, PIX_WIDTH, 


1 PIX HEIGHT) 
CALL X$SET_FOREGROUND (DPY, GC, DEFINE_COLOR(DPY, SCREEN, 
1 VISUAL, 2)) 


CALL X$DRAW_LINES(DPY, PIXMAP, GC, PT_ARR, 5, X$C_COORD_MODE) 
STATUS = XS$WRITE_BITMAP FILE(DPY, ’BITFILE.DAT’, PIXMAP, 
1 20, 20, 0, O) 


The client first creates a pixmap using the method described in Section 7.1 
and then calls the WRITE BITMAP FILE routine to write the pixmap data 
into the BITFILE.DAT bitmap file. 


To create a bitmap or pixmap from a bitmap data file, use either the 
CREATE BITMAP FROM DATA or CREATE PIXMAP FROM DATA 
routine. Example 7-3 illustrates creating a pixmap from the bitmap data 
stored in BITFILE.DAT. 
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Example 7-3 Creating a Pixmap from Bitmap Data 


LOGICAL*1 LINES (60) 
PARAMETER PIX WIDTH = 16, PIX_HEIGHT = 16 


DATA LINES /’AA’X, ‘’AA’X, 'OA’X, '55’X, '55'X, '05'X, 
‘"RA'X, ‘AALX, "OA'X, '55'X, '55'X, '05'X, ‘AA'X, 
"BAX, ‘OA'X, '55'X, '55'X, '05'X, “AA'X, ‘AA'X, 
‘OA’X, '55'X, '55'X, 'O5'X, ‘AA'X, 'AA’X, ‘OA'X, 
"55'X, '55'X, '05'X, "AA'X, “BAX, 'OA'X, °55'X, 
'55'X, 'O5’X, ‘AA'X, 'AA'X, ‘OA'X, '55'X, '55'X, 
'05’X, ‘AA’X, "AA'X, ‘OA'X, '55'X, '55'X, '05'X, 
“RA’X, “AA'X, "OA'X, '55'X, '55’X, '05’X, “AA'X, 
"BAX, 'OA'X, '55'X, '55'X, '05'X/ 


PREPRPEPRPPHE 


Create the pixmap 


aan 


PIX FOREGROUND = XGCVL.X$L_GCVL_FOREGROUND 

PIX BACKGROUND = XGCVL.X$L_GCVL_BACKGROUND 

PIXMAP = XS$CREATE PIX FROM BITMAP DATA(DPY, WINDOW, LINES, 
4. PIX WIDTH, PIX_HEIGHT, PIX_FOREGROUND, 

1 PIX BACKGROUND, DEPTH) 

CALL X$SET_WINDOW_ BACKGROUND PIXMAP(DPY, WINDOW, PIXMAP) 





The client uses the pixmap to define window background. 





Working with Images 


Instead of managing images directly, clients perform operations on them 
by using the image data structure, which includes a pointer to data such 
as the LINES array defined in Example 7-3. In addition to the image 
data, the image data structure includes pointers to client-defined functions 
that perform the following operations: 


e Destroying an image 

¢ Getting a pixel from the image 
e Storing a pixel in the image 

e Extracting part of the image 

¢ Adding a constant to the image 


If the client has not defined a function, the corresponding Xlib routine is 
called by default. 
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Figure 7-1 illustrates the data structure. 
Figure 7-1 Image Data Structure 


x$l_imag_width 

x$l_imag_height 
x$l_imag_xoffset 
x$l_imag_format 


x$a_imag_data 


x$l_imag_byte_order 


x$l_imag_bitmap_unit 
x$l_imag_bitmap_bit_order 


x$l_imag_bitmap_pad 


x$l_imag_depth 
x$l_imag_bytes_per_line 
x$l_imag_bits_per_pixel . 
x$l_imag_red_mask 


x$l_imag_green_mask 


x$l_imag_blue_mask 


x$a_imag_obdata 


x$a_imag_create_image 
x$a_imag_destroy_image 
x$a_imag_get_pixel 


x$a_imag_put_pixel 


x$a_imag_sub_image 


x$a_imag_add_pixel 


La | 
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Table 7-1 describes the members of the data structure. 


Table 7—1 


Member Name 


X$L_IMAG_WIDTH 
X$L_IMAG_HEIGHT 
X$L_IMAG_OFFSET 


X$L_IMAG_FORMAT 


X$A_IMAG_DATA 
X$L_IMAG_BYTE_ORDER 
X$L_IMAG_BITMAP_UNIT 
X$L_IMAG_BITMAP_BIT_ORDER 
X$L_IMAG_BITMAP_PAD 


X$L_IMAG_DEPTH 
X$L_IMAG_BYTES_PER_LINE 
X$L_IMAG_BITS_PER_PIXEL 
X$L_IMAG_RED_MASK 
X$L_IMAG_GREEN_MASK 
X$L_IMAG_BLUE_MASK 
X$A_IMAG_OBDATA 
X$A_IMAG_CREATE_IMAGE 
X$A_IMAG_DESTROY_IMAGE 
X$A_IMAG_GET_PIXEL 
X$A_IMAG_PUT_PIXEL 
X$A_IMAG_SUB_IMAGE 
X$A_IMAG_ADD_PIXEL 


Image Data Structure Members 


Contents 


Specifies the width of the image. 
Specifies the height of the image. 


Specifies the number of pixels offset in the x direction. Specifying an offset 
permits the server to ignore the beginning of scanlines and rapidly display 
images when Z pixmap format is used. 


Specifies whether the data is stored in XY pixmap or Z pixmap format. The 
following flags facilitate specifying data format: 


Fiag Name Description 


x$c_xy_bitmap 


x$c_xy_pixmap 
x$c_z_pixmap 


A single bitmap representing one plane 
A set of bitmaps representing individual planes 


Data organized as a list of pixel values viewed 
as a horizontal row 


Address of the image data. 

Indicates whether least significant or most significant byte is first. 
Specifies whether the bitmap is organized in units of 8, 16, or 32 bits. 
Specifies whether the bitmap order is least or most significant. 


Specifies whether padding in XY format or Z format should be done in 
units of 8, 16, or 32 bits. 


Depth of the image. 

Bytes per line to be used as an accelerator. 

Indicates for Z format the number of bits per pixel. 

Specifies the red value of Z format. 

Specifies the green value of Z format. 

Specifies blue values of Z format. 

A data structure that contains object routines. 

Client-defined function that creates an image. 

Client-defined function that destroys an image. 

Client-defined function that gets the value of a pixel in the image. 
Client-defined function that changes the value of a pixel in the image. 
Client-defined function that creates a new image from an existing one. 


Client-defined function that increments each pixel value in the image by a 
constant. 
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To create an image, use either the CREATE IMAGE or the GET IMAGE 
routine. CREATE IMAGE initializes an image data structure, including 
a reference to the image data. For example, the following call creates an 
image data structure that points to the image data LINES, illustrated in 
Example 7-3: 


RECORD /XSIMAGE/ IMAGE 


PARAMETER WINDOW_W = 600, WINDOW_H = 600, 
1 PIX WIDTH = 16, PIX HEIGHT = 16, 
1 BITMAP PAD 16, BYTES PER_LINE 16 


STATUS = X$CREATE_IMAGE(DPY, VISUAL, DEPTH, X$C_Z PIXMAP, 
1 0, LINES, PIX WIDTH, PIX_HEIGHT, BITMAP PAD, 
1 BYTES PER LINE, IMAGE) 


IF (STATUS .EQ. 0) THEN 
WRITE (6,*) ‘Image not created!’ 
CALL SYSS$EXIT (%VAL (1) ) 

ENDIF 


Note that the CREATE IMAGE routine does not allocate storage space for 
the image data. 


To create an image from a drawable, use the GET IMAGE routine. In the 
following example, the client creates an image from a pixmap: 


PARAMETER X_ ORIGIN = 0, Y_ORIGIN = 0, 
1 PIX WIDTH = 16, PIX_HEIGHT = 16 


IMAGE = X$GET_IMAGE(DPY, PIXMAP, X_ORIGIN, Y_ORIGIN, 
1 PIX_WIDTH, PIX_HEIGHT, XGCVL.X$L_GCVL_PLANE MASK, 
1 X$C_Z PIXMAP) 


When the client calls the GET IMAGE routine and the drawable is a 
window, the window must be mapped. In addition, if there are no inferiors 
or overlapping windows, the specified rectangle of the window should be 
fully visible on the screen and wholly contained within the outside edges 
of the window. In other words, an error results if the GET IMAGE routine 
is called to get a portion of a window that is off-screen. 
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To transfer an image from memory to a drawable, use the PUT IMAGE 
routine. In the following example, the client transfers the image from 
memory to a window: 


PARAMETER SRC_X 0, SRC_Y = 0, 
200, DST _Y = 


1 DST _X Y = 200, 
if PIX WIDTH = 16, PIX_HEIGHT = 16 


CALL X$PUT_IMAGE(DPY, WINDOW, GC, IMAGE, SRC_X, SRC_Y, 
1 DST_X, DST_Y, PIX_WIDTH, PIX_HEIGHT) 


The call transfers the entire image, which was created in the call to GET 
IMAGE, from memory to coordinates (200, 200) in the window. 


As the description of the image data structure indicates, Xlib enables 
clients to store an image in the following ways: 


e Asa bitmap—xXyY bitmap format stores the image as a two-dimensional 
array. Figure 7—2 illustrates XY bitmap format. 


e Asa set of bitmaps—XY pixmap format stores the image as a stack of 
bitmaps. Figure 7-3 illustrates XY pixmap format. 


e 6As a list of pixel values—Z pixmap format stores the image as a list of 
pixel values viewed as a horizontal row. Each example of creating an 
image uses Z pixmap format. Figure 7—4 illustrates scanline order. 


Figure 7-2 XY Bitmap Format 


XY Bitmap Format 


Boo 


ZK-0157A-GE 
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Figure 7-3. XY Pixmap Format 





XY Pixmap Format 
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Figure 7-4 Z Format 





Z Pixmap Format 
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Xlib includes routines to change images by manipulating their pixel values 
and creating new images out of subsections of existing images. Table 7-2 
lists these routines and their use. Clients can override these routines by 
defining functions referred to in the image data structure. 
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Table 7-2 Routines That Change Images 


Routine Description 


ADD PIXEL increments each pixel in an image by a constant value 

GET PIXEL Returns the pixel value of an image 

PUT PIXEL Sets the pixel value of an image 

SUB IMAGE Creates a new image out of a subsection of an existing image 





When a client no longer needs an image, use the DESTROY IMAGE 
routine to deallocate memory associated with the image data structure. 
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This chapter describes writing text using Xlib. The chapter includes the 
following topics: 


¢ Characters and fonts—A description of the composition of characters 
and types of fonts and their components 


e §6Specifying fonts—How to load a font and associate it with a graphics 
context 


¢ Computing text size—How to determine the size of text 

¢ Getting information about text—How to get information about text 
¢ Drawing text—How to write text on the screen 

VMS DECwindows provides a font compiler to enable programmers 


to convert ASCII files into binary form. For a guide to using the font 
compiler, see Appendix A. 





8.1 Characters and Fonts 


The smallest unit of text the server displays on a screen is a character. 
Pixels that form a character are enclosed within a bounding box that 
defines the number of pixels the server turns on or off to represent the 
character on the screen. For example, Figure 8—1 illustrates the bounding 


box that encloses the character “y.” 


The server turns each pixel within the bounding box either on or off, 
depending on the character. Consequently, bounding box size affects 
performance. Larger bounding boxes require more server time to process 
than do smaller boxes. 


The character is positioned relative to the baseline and the character 
origin. The baseline is logically viewed as the x axis that runs just below 
nondescending characters. The character origin is a point along the 
baseline. The left bearing of the character is the distance from the origin 
to the left edge of the bounding box; the right bearing is the distance 
from the origin to the right edge. Ascent and descent measure the 
distance from the baseline to the top and bottom of the bounding box, 
respectively. Character width is the distance from the origin to the next 
character origin ( x + width, y). 
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Figure 8-1 Composition of a Character 
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Figure 8—2 illustrates that the bounding box of a character can extend 
beyond the character origin. The bounding box of the slash extends one 
pixel to the left of the origin of the slash, giving the character a left 
bearing of —1. The slash is also unusual because its bounding box extends 
to the right of the next character. The width of the slash, measured from 
origin to origin, is 5; the right bearing, measured from origin to the right 
edge of the bounding box, is 6. 
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Figure 8-2 Composition of a Slash 
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The left bearing, right bearing, ascent, descent, and width of a character 
are its character metrics. Xlib maintains information about character 
metrics in a char struct data structure. Figure 8-3 illustrates the data 
structure. 


Figure 8-3 Char Struct Data Structure 





x$w_char_rbearing x$w_char_lbearing 
x$w_char_attributes x$w_char_descent 


Table 8-1 describes members of the char struct data structure. Any 
member of the data structure can have a negative value, except the 
X$W_CHAR_ATTRIBUTES member. 
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Table 8-1 Char Struct Data Structure Members 


Member Name Contents 

X$W_CHAR_LBEARING Distance from the origin to the left edge of the 
bounding box. 

X$W_CHAR_RBEARING Distance from the origin to the right edge of the 
bounding box. 

X$W_CHAR_WIDTH Distance from the current origin to the origin of 


the next character. Text written left to right, such 
as Arabic, uses a negative width to place the next 
character to the left of the current origin. 


X$W_CHAR_ASCENT Distance from the baseline to the top of the 
bounding box. 

X$W_CHAR_DESCENT Distance from the baseline to the bottom of the 
bounding box. 

X$W_CHAR_ATTRIBUTES Attributes defined in the bitmap distribution format 
file. A character is not guaranteed to have any 
attributes. 


A font is a group of characters that have the same style and size. Xlib 
supports both fixed and proportional fonts. A fixed font has equal 
metrics. For example, all characters in the font have the same value 
for left bearing. Consequently, the bounding box for all characters is the 
same. All metrics in a proportional font can vary from character to 
character. A monospaced font is.a special type of proportional font in 
which only the width of all characters must be equal. Bounding boxes of 
characters in a monospaced font vary depending on the size of characters. 
If the same font is compiled as a monospaced font and a fixed font, the 
bounding boxes of the monospaced font are typically smaller than the 
bounding box that encloses fixed-font characters. For information about 
compiling fonts, see Appendix A. 


Xlib uses indexes to refer to characters that compose a font. The indexes, 
each defined by a byte, are arranged in one or more rows of up to 256 
indexes. A font can contain as many as 256 rows of character indexes, 
used contiguously. Fonts seldom use all possible indexes. 


For example, the font illustrated in Figure 8-4 comprises 219 characters 
in columns 32 through 250, one column for each character index. Columns 


- 1 through 31 and 251 through 256 are undefined. The first character of 


the font is located at column 32; the last character is located at column 
250. Because all characters are defined in one row of 256 indexes, the 
font is a single-row font. In the illustration, character “A” is located at 
column 65. 
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Figure 8—4 Single-Row Font 
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Multiple-row fonts, such as Kanji, comprise more characters than 

can be indexed by a single row of 256 bytes. Figure 8-5 illustrates the 
configuration of a multiple-row font. Byte 1 refers to the row. Byte 2 
refers to the column in the row. In Figure 8-5, the character is located at 
column 36 in row 17. Note that each row of a multiple-row font has the 
same number of undefined bytes at the beginning and end. In each row, 
characters begin at column 32 and end at column 250. 


Figure 8-5 Multiple-Row Font 
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Xlib provides a char 2B data structure to enable clients to index multiple- 
row fonts easily. Figure 8—6 illustrates the data structure. 


Figure 8-6 Char 2B Data Structure 


x$t_ch2b_byte2 x$t_ch2b_byte1 
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Table 8-2 describes members of the data structure. 


Table 8-2 Char 2B Data Structure Members 


Member Name Contents 
X$T_CHAR2B_BYTE1 Row in which the character is indexed 
X$T_CHAR2B_BYTE2 Position of the character in the row 


Xlib provides clients a font struct data structure to record the 
characteristics of single-row and multiple-row fonts. Figure 8-7 illustrates 
the font struct data structure. 


Figure 8-7 Font Struct Data Structure 
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Figure 8-7 (Cont.) Font Struct Data Structure 


x$a_fstr_per_char 


x$l_fstr_ascent 


x$l_fstr_descent 





Table 8-3 describes members of the data structure. 


Table 8-3 Font Struct Data Structure Members 


Member Name 


X$A_FSTR_EXT_DATA 
X$L_FSTR_FID 
X$L_FSTR_DIRECTION 


X$L_FSTR_MIN_CHAR_OR_BYTE2 
X$L_FSTR_MAX_CHAR_OR_BYTE2 
X$L_FSTR_MIN_BYTE1 
X$L_FSTR_MAX_BYTE1 
X$L_FSTR_ALL_CHARS_EXIST 


X$L_FSTR_DEFAULT_CHAR 


X$L_FSTR_N_PROPERTIES 
X$A_FSTR_PROPERTIES 


X$R_FSTR_MIN_BOUNDS 


Contents 


Data used by extensions. 
Identifier of the font. 


Hint about the direction in which the font is painted. The direction 
can be either left to right, specified by the constant x$c_font_left_ 
to_right, or right to left, specified by the constant x$c_font_right_to_ 
left. The core protocol does not support vertical text. 

First character in the font. 

Last character in the font. 

First row that exists. 

Last row that exists. 

lf the value of this member is true, all characters in the array 
pointed to by X$A_FSTR_PER_CHAR have nonzero bounding 
boxes. 

Character used when an undefined or nonexistent character is 
printed. The default character is a 16-bit, not a 2-byte, character. 
For a multiple-row font, X$L_FSTR_DEFAULT_CHAR has byte 1 in 
the most significant byte and byte 2 in the least significant byte. If 
X$L_FSTR_DEFAULT_CHAR specifies an undefined or nonexistent 
character, the server does not print an undefined or nonexistent 
character. 

Number of properties associated with the font. 


Address of an array of font prop data structures that define font 
properties. For a description of the font prop data structure, see 
Section 8.3 


Minimum metrics values of all the characters in the font. The 
metrics define the left and right bearings, ascent and descent, and 
width of characters. 


For a description of the use of X¥$R_FSTR_MIN_BOUNDS, see 
X$R_FSTR_MAX_BOUNDS. 





(continued on next page) 


8—7 


Writing Text 


8.1 Characters and Fonts 


Table 8-3 (Cont.) Font Struct Data Structure Members 


Member Name 


Contents 





X$R_FSTR_MAX_BOUNDS 


X$A_FSTR_PER_CHAR 


X$L_FSTR_ASCENT 


X$L_FSTR_DESCENT 


Maximum metrics values of all the characters in the font. 


Using the values of X$R_FSTR_MIN_BOUNDS and X$R_FSTR_ 
MAX_BOUNDS, clients can compute the bounding box of a font. 
The bounding box of the font is determined by first computing the 
minimum and maximum value of the left bearing, right bearing, 
width, ascent, and descent of all characters and then subtracting 
minimum from maximum values. The upper left coordinate of the 
font bounding box (x, y) is defined as follows: 


x + X$R_FSTR_MIN_BOUNDS.X$W_CHAR_LBEARING, 
y - X$R_FSTR_MAX BOUNDS.X$W_CHAR_ASCENT 


The width of the font bounding box is defined as follows: 


X$R_FSTR_MAX BOUNDS.X$W_CHAR_RBEARING - 
X$R_FSTR MIN BOUNDS.X$W_CHAR_LBEARING 


Note that this is not the width of a font character. 
The height is defined as follows: 


X$R_FSTR_MAX_BOUNDS.X$W_CHAR_ASCENT + 
X$R_FSTR_MAX BOUNDS.X$W_CHAR_DESCENT 


Address of an array of char struct data structures that define each 
character in the font. For a fixed font, the value of this member is 
null. 


Distance from the baseline to the top of the bounding box. With 
X$L_FSTR_DESCENT, X$L_FSTR_ASCENT is used to determine 
line spacing. Specific characters in the font may extend beyond the 
font ascent. 


The distance from the baseline to the bottom of the bounding 
box. With X$L_FSTR_ASCENT, X$L_FSTR_DESCENT is used to 
determine line spacing. Specific characters in the font may extend 
beyond the font descent. 





As Table 8-3 indicates, Xlib records metrics for each character in an array 
of char struct data structures specified by the font struct X$A_FSTR_PER_ 


CHAR member. The array comprises as many char struct data structures 
as there are characters in the font. However, the indexes that refer to the 


location of characters in the array differs from the indexes to characters in 
the font. For example, 32 indexes the first character of the font illustrated 
in Figure 8-8, whereas 0 indexes its char struct data structure in the 
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Figure 8-8 Indexing Single-Row Font Character Metrics 


Last Character, | yg First Character 
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Array of Char Struct Structures 


Char Struct | 1 Defines Metrics of First Character (32) 
Char Struct |2 Defines Metrics of Second Character (33) 


Char Struct {34 Defines Metrics of "A" (65) 


Char Struct |219 Defines Metrics of Last Character 





ZK-0271A-GE 


To locate the char struct data structure that defines the metrics of any 
character in a single-row font, subtract the value of the column that 
indexes the first character in the font, specified by X$L_FSTR_MIN_ 
CHAR_OR_BYTE_2, from the position of the character. Then add 1 to 
this number. For instance, in Figure 8-8 the metrics of character “A” are 
located at index 34 in the array of char struct data structures specified by 
the X$A_FSTR_PER_CHAR member. 


To locate the char struct data structure that defines the metrics of a 
character of a multiple-row font, use the following formula to adjust for 
both the number of rows in the font and the position of the character in a 
row: 


(row — first row of characters) « N + (position in column — first column) 


N is equal to the last column minus the first column plus 1. 


For example, the array index of the character specified in Figure 8-9 is 
443, 
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Figure 8-9 indexing Multiple-Row Font Character Metrics 
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a Font Characters 
Array of Char Struct Structures 
Char Struct |1 Defines Metrics of Character at Row 15, Column 32 


Char Struct {219 Defines Metrics of Character in Row 15, Column 250 
220 Defines Metrics of Character in Row 16, Column 32 


Char Struct [443 Defines Metrics of Char 2B Character 


Char Struct 52997 Defines Metrics of Last Character 
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Like windows, fonts may have properties associated with them. However, 
font properties differ from window properties. Window properties are data 
associated with windows; font properties describe font characteristics, such 
as spacing between words. When the font is compiled, its properties are 
defined in an array of font prop data structures. 
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Just as atoms name window properties, atoms name font properties. If 
the atoms are predefined, they have associated literals. For example, the 
predefined atom that identifies the height of capitalized letters is referred 
to by the literal X$C_XA_CAP_HEIGHT. 


When working with properties, clients must know beforehand how to 
interpret the font property identified by an atom. Figure 8—10 illustrates 
this concept. 


The server maintains an atom table for font properties. The table 
associates values with strings. For example, the atom table illustrated 

in Figure 8-10 defines two atoms. One associates the string FULL_NAME 
with the value 41. The other associates the string CAP_HEIGHT with 
the value 42. Notice that the string in the atom table is different from 
X$C_XA_FULL_NAME, the literal that refers to the atom. 


Both atoms uniquely identify different types of data. FULL_NAME 
identifies string data that names the font. CAP_HEIGHT identifies integer 
data that defines the size of capitalized letters. 


Although the atoms identify different types of data, the property table 
illustrated in Figure 8-10 associates both atoms with integers. The integer . 
associated with CAP_HEIGHT defines without further interpretation the 
height of capitalized letters. However, the integer listed with FULL_ 
NAME is an atom value. This integer, 90, corresponds to a value in the 
atom table that has an associated string, HELVETICA BOLD. To use the 
string, the client must know that the value associated with the atom is 
itself an atom value. 
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Figure 8-10 Atoms and Font Properties 


Atom Table 
Value String 


Literals 


— X$C_XA_FULL_NAME 
<< X$C_XA_CAP_HEIGHT 
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FONT PROP (n) 
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Xlib lists each font property and its corresponding atom in a font prop data 
structure. The property value table in Figure 8-10 is an array of font prop 
data structures. . 


Figure 8-11 illustrates the font prop data structure. 
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Figure 8-11 Font Prop Data Structure 





x$l_fntp_name 
x$l_fntp_card32 


Table 8—4 describes members of the data structure. 





Table 84 Font Prop Data Structure Members 
Member Name Contents a. 





X$L_FNTP_NAME String of characters that names the property 
X$L_FNTP_CARD32 A 32-bit value that defines the font property 
Specifying a Font 


To specify a font for writing text, first load the font and then 
associate the loaded font with a graphics context. The font 

files are stored in SYS$SYSROOT:[SYSFONT.DECW.75DPI] and 
SYS$SYSROOT:[SYSFONT.DECW.100DPI]. Appendix D lists VMS 
DECwindows font names. 


To load a font, use either the LOAD FONT or the LOAD QUERY FONT 
routine. LOAD FONT loads the specified font and returns a font identifier. 
LOAD QUERY FONT loads the specified font and returns information 
about the font to a font struct data structure. 


Because LOAD QUERY FONT returns information to a font struct data 
structure, calling the routine takes significantly longer than calling LOAD 
FONT, which returns only the font identifier. 


When using either routine, pass the display identifier and font name. Xlib 
font names consist of the following fields, in left to right order: 


-1 Foundry that supplied the font, or the font designer 
Typeface family of the font 

Weight (book, demi, medium, bold, light) 

Style (R (roman), I (italic), O (oblique)) 


Width per horizontal unit of the font (normal, wide, double wide, 
narrow) 


Additional style font identifier 
Pixel font size 
Point size (8, 10, 12, 14, 18, 24) 


Resolution in pixels/dots per inch 


a fF © ND 


oo n ® 
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10 Spacing (monospaced, proportional, or character cell) 
11 Average width of all characters in the font 
12 Set character encoding 


The full name of a representative font is as follows: 


~ADOBE-ITC Avant Garde Gothic-Book-R-Normal--14-100-100-100-—P~80-IS08859-1 


The font is named ITC Avant Garde Gothic. Font weight is book, font style 
is R (roman), and width between font units is normal. 


The pixel size is 14 and the decipoint size is 100. 


Horizontal and vertical resolution in dots per inch (dpi) is 100. When the 
dpi is 100, 14 pixels are required to be a 10 point font. 


The font is proportionally spaced. Average width of characters is 80. 
Character encoding is ISOLATIN1. j 


The following designates the full name of the comparable font designed for 


_a 75 dpi system: 


-ADOBE-ITC Avant Garde Gothic-Book-R-Normal--10-100-75-75-P-59-IS08859-1 


Unlike the previous font, this font requires only 10 pixels to be 10 points. 


- Note that this font differs from the previous font only in pixel size, 


resolution, and character width. 


Xlib enables clients to substitute a question mark for a single character 
and an asterisk for one or more fields in a font name. The following 
illustrates using the asterisk to specify a 10-point ITC Avant Garde Gothic 
font of book weight, roman style, and normal spacing for display on either 
75 or 100 dpi systems: 


-ADOBE-ITC Avant Garde Gothic-Book-R-Normal--*-100-*-*-P-* 


When using the asterisk, make sure that substitutions are clearly defined. 
For example, the following name ambiguously specifies two fonts: 


~ADOBE-ITC Avant Garde Gothic-Book-R-Normal--*-100-*-P-* 


Because the leftmost asterisk substitutes for all fields before the 100, the 
name defines the following two 100 dpi fonts: 


~ADOBE-ITC Avant Garde Gothic-—Book-R-Normal--11-80-100-100-P-80-1I1S08859-1 


~ADOBE-ITC Avant Garde Gothic-Book~R-Normal—--14-100-100-100-P-80-IS08859-1 


The first is an 8 point font. The second is a 10 point font. 
The following example illustrates loading the 10-point font: 


CHARACTER*58 FONT NAME 


DATA FONT NAME 


1 /'-ADOBE-ITC AVANT GARDE GOTHIC-BOOK-R-NORMAL-~-*-100-*-—*—-—Pp—*! / 


FONT = X$LOAD_FONT(DPY, FONT _NAME) 
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After loading a font, associate it with a graphics context by calling the 
SET FONT routine. Specify the font identifier that either LOAD FONT or 
LOAD QUERY FONT returned, and a graphics context, as in the following 
example: 


CALL X$SET_FONT(DPY, GC, FONT) 
The call associates FONT with GC. 


When loading fonts, note that the LOAD FONT routine is an asychronous 
routine and does not return an error if the call is unsuccessful. Use one of 
the following three methods to determine the validity of the font id: 


¢ Force the error by calling the SYNC routine and using an error 
handler. (For more information about this method, refer to 
Section 9.13.3.) 


¢ Check that the font exists by calling the LIST FONTS routine, and 
load the font by calling the LOAD FONT routine. 


e Use the LOAD QUERY FONT routine. LOAD QUERY FONT is a 
synchronous routine that loads the font, returns a pointer to a font 
struct data structure, and checks that the call is successful. However, 
note that because LOAD QUERY FONT returns information to a font 
struct data structure, calling the routine takes significantly longer 
than calling LOAD FONT, which returns only the font identifier. 


8.3 Getting Information About a Font 


Xlib provides clients with routines that list available fonts, get font 
information with or without character metrics, and return the value of 
a specified font property. 


To get a list of available fonts, use the LIST FONTS routine, specifying the 
font searched for. 


LIST FONTS returns a list of available fonts that match the specified font 
name. 


To receive both a list of fonts and information about the fonts, use the 
LIST FONTS WITH INFO routine. LIST FONTS WITH INFO returns 
both a list of fonts that match the font specified by the client and the 
address of a font struct data structure for each font listed. Each data 
structure contains information about the font. The data structure does not 
include character metrics in the X$A_FSTR_PER_CHAR member. For a 
description of the information returned, see Table 8-3. 


To receive information about a font, including character metrics, use the 
QUERY FONT routine. Because the server returns character metrics, 
calling QUERY FONT takes approximately eight times longer than calling 
LIST FONTS WITH INFO. To get the value of a specified property, use the 
GET FONT PROPERTY routine. 


Although a font is not guaranteed to have any properties, it should have 
at least the properties described in Table 8-5. The table lists properties 
by atom name and data type. For information about properties, see 
Section 3.5. — 
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Table 8-5 Atom Names of Font Properties 


Atom Data Type Description of the Property 

X$C_XA_MIN_SPACE Unsigned Minimum interword spacing, in pixels. 
X$C_XA_NORMAL_SPACE Unsigned Normal interword spacing, in pixels. 
X$C_XA_MAX_SPACE Unsigned Maximum interword spacing, in pixels. 
X$C_XA_END_SPACE Unsigned Additional spacing at the end of a sentence, in pixels. 
X$C_XA_SUPERSCRIPT_X Signed With X$C_XA_SUPERSCRIPT_Y, the offset from the 


character origin where superscripts should begin, in 
pixels. If the origin is [x, y], superscripts should begin at 
the following coordinates: 


x + X$C_XA_SUPERSCRIPT_X, 
y - X$C_XA SUPERSCRIPT Y 


X$C_XA_SUPERSCRIPT_Y Signed . With X$C_XA_SUPERSCRIPT_X, the offset from 
the character origin where superscripts should begin, 
in pixels. See the description under X$C_XA_ 
SUPERSCRIPT_X. 


X$C_XA_SUBSCRIPT_X Signed With X$C_XA_SUBSCRIPT_Y, the offset from the 
character origin where subscripts should begin, in pixels. 
If the origin is [x, y], subscripts should begin at the 
following coordinates: 


x + X$C_XA_ SUBSCRIPT X, 
y + X$C_XA_SUBSCRIPT_Y 

X$C_XA_SUBSCRIPT_Y Signed With X$C_XA_SUBSCRIPT_X, the offset from the 
character origin where subscripts should begin, in pixels. 
See the description under X$C_XA_SUBSCRIPT_X. 


X$C_XA_UNDERLINE_POSITION Signed The y offset from the baseline to the top of an underline, 
in pixels. If the baseline y-coordinate is y, then the 
top of the underline is at y + X$C_XA_UNDERLINE__ 


POSITION. 
X$C_XA_UNDERLINE_ THICKNESS Unsigned Thickness of the underline, in pixels. 
X$C_XA_STRIKEOUT_ASCENT Signed With X$C_XA_STRIKEOUT_DESCENT, the vertical 


extent for boxing or voiding characters, in pixels. If the 
baseline y-coordinate is y, the top of the strikeout box is 
y - X$C_XA_STRIKEOUT_ASCENT. The height of the 
box is as follows: 


X$C_XA_STRIKEOUT_ASCENT + 
X$C_XA_STRIKEOUT_DESCENT 


X$C_XA_STRIKEOUT_DESCENT Signed With X$C_XA_STRIKEOUT_ASCENT, the vertical extent 
for boxing or voiding characters, in pixels. See the 
description under X$C_XA_STRIKEOQUT_ASCENT. 


X$C_XA_ITALIC_ANGLE Signed The angle of the dominant staffs of characters in the font, 
in degrees scaled by 64, relative to the 3-o’clock position 
from the character origin. Positive values indicate 
counterclockwise motion. 





(continued on next page) 
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Table 8—5 (Cont.) Atom Names of Font Properties 


Atom 


X$C_XA_X_HEIGHT 
X$C_XA_QUAD_WIDTH 


X$C_XA_CAP_HEIGHT 


X$C_XA_WEIGHT 
X$C_XA_POINT_SIZE 
X$C_XA_RESOLUTION 


X$C_XA_COPYRIGHT 
X$C_XA_NOTICE 
X$C_XA_FONT_NAME 
X$C_XA_FAMILY_NAME 
X$C_XA_FULL_NAME 


Data Type 
Signed 


Signed 


Signed 


Unsigned 
Unsigned 
Unsigned 


Unsigned 
Unsigned 
Atom 
Atom 
Atom 


Description of the Property 
One ex, as in TeX, but expressed in units of pixels. 
Often the height of lowercase x. 


One em, as in TeX, but expressed in units of pixels. 
Often the width of the digits 0 to 9. 


The y offset from the baseline to the top of capital letters, 
ignoring ascents. If the baseline y-coordinate is y, the 
top of the capitals is at y - X$C_XA_CAP_HEIGHT. 


Weight or boldness of the font, expressed as a value 
between 0 and 1000. 


Point size of the font at ideal resolution, expressed in 
1/10 points. 


Number of pixels per point, expressed in 1/100, at which 
the font was created. 


Copyright date of the font. 
Copyright date of the font name. 
Font name. 

Name of the font family. 

Full name of the font. 





Freeing Font Resources 


Because allocating fonts requires large amounts of memory, it is important 
to deallocate these resources when the client no longer needs them. 

Table 8-6 lists complimentary font routines and the result when the 
deallocating routine is called. 


Table 8-6 Complimentary Font Routines 


Allocating Routine 


LOAD FONT 


LOAD QUERY FONT 


Deallocating Routine 


UNLOAD FONT 


FREE FONT 


UNLOAD FONT 


Result 


Deletes the association between the font resource 
ID and the specified font and unloads it from server 
memory 


Unloads and frees the storage used by the font 
structure 


Unloads the font from server memory 


Note that because the routines LIST FONTS and LIST FONT WITH INFO 
return the font information via a single descriptor, the deallocating routine 
FREE FONT NAMES is not needed. 
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Computing the Size of Text 


Use the TEXT WIDTH and TEXT WIDTH 16 routines to compute the 
width of 8-bit and 2-byte strings, respectively. The routines return the 
sum of the width of each character in the specified string. To compute the 
bounding box of a specified 8-bit string, use either the TEXT EXTENTS 
or QUERY TEXT EXTENTS routine. Both TEXT EXTENTS and QUERY 
TEXT EXTENTS return the direction hint, ascent, descent, and overall 
size of the character string being queried. 


TEXT EXTENTS passes to Xlib the font struct data structure returned 
by a previous call to either LOAD QUERY FONT or QUERY FONT. 
QUERY TEXT EXTENTS queries the server for font information, which 
the server returns to a font struct data structure. Because Xlib can process 
TEXT EXTENTS locally, without querying the server for font metrics, 
calling TEXT EXTENTS is significantly faster than calling QUERY TEXT 
EXTENTS. 


To compute the bounding boxes of a specified 2-byte string, use either the 
TEXT EXTENTS 16 or the QUERY TEXT EXTENTS 16 routine. Both 
routines return information identical to information returned by TEXT 
EXTENTS and QUERY TEXT EXTENTS. As with TEXT EXTENTS, 
calling TEXT EXTENTS 16 is significantly faster than calling QUERY 
TEXT EXTENTS 16 because Xlib can process the call without making the 
round-trip to the server. 





Drawing Text 


Xlib enables clients to draw text stored in text data structures, text 
whose foreground bits are only displayed, and text whose foreground and 
background bits are displayed. 


To draw 8-bit or 2-byte text stored in data structures, use either the 
DRAW TEXT or the DRAW TEXT 16 routine. Xlib includes text item and 
text item 16 data structures to enable clients to store text. Figure 8-12 
illustrates the text item data structure. 


Figure 8-12 Text Item Data Structure 
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Table 8-7 describes members of the text item data structure. 


Table 8-7 Text Item Data Structure Members 


Member Name Contents 

X$A_TEXT_CHARS Address of a string of characters. 
X$L_TEXT_N_ CHARS Number of characters in the string. 
X$L_TEXT_DELTA Horizontal spacing before the start of the string. 


Spacing is always added to the string origin and is not 
dependent on the font used. 


X$L_TEXT_FONT Identifier of the font used to print the string. If the 
value of this member is x$c_none, the server uses the 
current font in the GC data structure. If the member 
has a value other than x$c_none, the specified font is 
stored in the GC data structure. 


Figure 8-13 illustrates the text item 16 data structure. 
Figure 8-13 Text Item 16 Data Structure 










Table 8—8 describes members of the text item 16 data structure. 









Table 8-8 Text Item 16 Data Structure Members 


Member Name Contents 


X$A_TX16_CHARS Address of a string of characters stored in a char 2B 
data structure. For a description of the char 2B data 
structure, see Figure 8-6. 


X$L_TX16_N_CHARS Number of characters in the string. 


X$L_TX16_DELTA Horizontal spacing before the start of the string. Spacing 
is always added to the string origin and is not dependent 
on the font used. 


(continued on next page) 
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Table 8-8 (Cont.) Text Item 16 Data Structure Members 


Member Name Contents 


X$L_TX16_FONT Identifier of the font used to print the string. If the value 
of this member is x$c_none, the server uses the current 
font in the GC data structure. If the member has a value 
other than x$c_none, the specified font is stored in the 
GC data structure. 





Xlib processes each text item in turn. Each character image, as defined by 
the font in the graphics context, is treated as an additional mask for a fill 
operation on the drawable. The drawable is modified only where the font 
character has a bit set to 1. 


Example 8-1 illustrates using the DRAW TEXT routine to draw three 
words in one call. 


Example 8-1 Drawing Text Using the DRAW TEXT Routine 





RECORD /X$TEXT_ITEM/ TEXT_ARR (3) 


CHARACTER*57 FIRST FONT 
DATA FIRST FONT 
1 /’-ADOBE-NEW CENTURY SCHOOLBOOK-BOLD-R-NORMAL--*-80-*-*—-P—*! / 


CHARACTER*58 SECOND_FONT 
DATA SECOND _FONT 
1 /'-ADOBE-NEW CENTURY SCHOOLBOOK-BOLD-R-NORMAL--—*-140-*-*—-P=—*/ / 


CHARACTER*58 THIRD FONT 
DATA THIRD FONT 
1 /’-ADOBE-NEW CENTURY SCHOOLBOOK-BOLD-R-NORMAL~~*-240-*-*=-P-*/ / 


CHARACTER*5 FIRST WORD 
DATA FIRST_WORD /’ SMALL’ / 


CHARACTER*6 SECOND WORD 
DATA SECOND _WORD /’ BIGGER’ / 


CHARACTER*7 THIRD WORD 
DATA THIRD_WORD /’BIGGEST’ / 


C Load the fonts for text writing 


FONT 1 = XSLOAD_FONT(DPY, FIRST_FONT) 


TEXT_ARR(1) .X$A_TEXT_CHARS = %LOC (FIRST_WORD) 
TEXT _ARR(1) .X$L_TEXT_N_CHARS = 5. 

TEXT ARR(1).X$L_TEXT DELTA = 0 

TEXT ARR(1) .X$L_TEXT FONT = FONT 1 


FONT 2 = X$LOAD_FONT(DPY, SECOND_FONT) 
CALL X$SET_FONT(DPY, GC, FONT 2) 





(continued on next page) 
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Example 8-1 (Cont.) Drawing Text Using the DRAW TEXT Routine 





aan 


TEXT_ARR(2) .X$A_TEXT CHARS = %LOC (SECOND_WORD) 


TEXT ARR(2).X$L_TEXT N CHARS = 6 
TEXT _ARR(2).X$L_TEXT DELTA = 20 
TEXT_ARR(2) .X$L_TEXT FONT = FONT 2 


FONT_3 = XSLOAD FONT(DPY, THIRD_FONT) 


TEXT_ARR(3) .X$A_TEXT_CHARS = %LOC(THIRD_WORD) 


'TEXT_ARR (3) exoby TEXT | N_ CHARS = 7 


TEXT_ARR(3).X$L_TEXT DELTA = 20 
TEXT_ARR(3).X$L_TEXT FONT = FONT 3 


Handle events 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT(DPY, EVENT) 
IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN 


CALL XSDRAW_ IMAGE STRING(DPY, WINDOW, GC, 
1 150, 25, ’To draw text, click MB1’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 50, ‘To exit, click MB2’) 
END IF 
IF (EVENT.EVNT TYPE .EQ. X$C_| BUTTON PRESS .AND. 
1 EVENT .EVNT ' BUTTON. X$L_ BTEV BUTTON -EQ. X$C_BUTTON1) THEN 
CALL XSDRAW | TEXT (DPY, WINDOW, GC, 100, 200, TEXT ARR(1), 3) 
END IF 
IF (EVENT.EVNT TYPE .EQ. XSC BUTTON _: PRESS .AND. 
1 EVENT. EVNT . | BUTTON. XSL BIEV ' BUTTON -EQ. X$C | BUTTON2) THEN 
CALL SYSSEXIT (%VAL(1)). 
END IF 
END DO 





To draw 8-bit or 2-byte text, use the DRAW STRING, DRAW STRING 

16, DRAW IMAGE STRING, and DRAW IMAGE STRING 16 routines. 
DRAW STRING and DRAW STRING 16 display the foreground values of 
text only. DRAW IMAGE STRING and DRAW IMAGE STRING 16 display 
both foreground and background values. 


Example 8-2 illustrates drawing text with the DRAW STRING routine. 
The example modifies the sample program in Chapter 1 to draw shadow 
text. 
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Example 8-2 Drawing Text Using the DRAW STRING Routine 





IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE .AND. 
1 EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW_2) THEN 
CALL X$CLEAR_WINDOW(DPY, WINDOW 2) 
CALL X$SET_FOREGROUND (DPY, GC, 


1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 3) ) 
CALL X$DRAW_STRING(DPY, WINDOW_2, GC, 

1 35, 75, MESSAGE (STATE) ) 
CALL X$SET_FOREGROUND (DPY, GC, 

1 DEFINE COLOR(DPY, SCREEN, VISUAL, 4) ) 
CALL X$DRAW_STRING(DPY, WINDOW_2, GC, 

a 31, 71, MESSAGE (STATE) ) 


END IF 


IF (EVENT.EVNT_ TYPE .EQ. X$C_BUTTON PRESS) THEN 
IF (EVENT.EVNT_EXPOSE.X$L_EXEV WINDOW .EQ. W.NDOW_1) THEN 
STATE = 2 | : 
CALL X$CLEAR_WINDOW(DPY, WINDOW 2) 
CALL X$SET_FOREGROUND (DPY, GC, 


1 DEFINE COLOR(DPY, SCREEN, VISUAL, 3)) 
CALL X$DRAW_STRING(DPY, WINDOW_2, GC, 

1 35, 75, MESSAGE (STATE) ) 
CALL X$SET_FOREGROUND (DPY, GC, 

1 DEFINE COLOR(DPY, SCREEN, VISUAL, 4)) 
CALL X$DRAW_STRING(DPY, WINDOW 2, GC, 

1 31, 71, MESSAGE (STATE) ) 

ELSE 


Unmap and destroy windows 


aaa 


CALL XSUNMAP_WINDOW(DPY, WINDOW_1) 
CALL X$DESTROY_WINDOW(DPY, WINDOW_1) 
CALL X$CLOSE_DISPLAY (DPY) 
CALL SYSSEXIT(%VAL(1) ) 
END IF 
END IF 
END DO 


END 





The server refers to the following members of the GC data structure when 
writing text with DRAW TEXT, DRAW TEXT 16, DRAW STRING, and 
DRAW STRING 16: 


Function Plane mask 
Foreground Subwindow mode 
Stipple Font 

Background Tile 

Tile stipple x origin Tile stipple y origin 
Clip x origin Clip y origin 

Clip mask Fill style 
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To draw both foreground and background values of text, use the DRAW 
IMAGE STRING and DRAW IMAGE STRING 16 routines. For example, 
the sample program uses the DRAW IMAGE routine to write the text 
“Click Here to Exit,” as follows: 


INTEGER*4 STATE 'flag for text 


CHARACTER*19 MESSAGE (2) 
DATA MESSAGE /’Click here to exit ’, ’Click HERE to exit!’/ 


CALL X$DRAW_IMAGE STRING(DPY, WINDOW _2, GC, 
1 75, 75, MESSAGE (STATE) ) 


The effect is first to fill a rectangle with the background defined in the 
graphics context and then to paint the text with the foreground pixel. The 
upper left corner of the filled rectangle is at 75,(75 — font ascent). The 
width of the rectangle is equal to the width of the string. The height of the 
rectangle is equal to font ascent + font descent. 


When drawing text in response to calls to DRAW IMAGE STRING and 
DRAW IMAGE STRING 16, the server ignores the function and fill style 
the client has defined in the graphics context. The value of the function 
member of the GC data structure is effectively the value specified by the 
constant x$c_gx_copy. The value of the fill style member is effectively 
the value specified by the constant x$c_fill_solid. 


The server refers to the following members of the GC data structure when 
writing text with DRAW IMAGE STRING and DRAW IMAGE STRING 16: 


Subwindow mode Plane mask 


Foreground Background 
Stipple Font 

Clip x origin Clip y origin 
Clip mask 
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9.1 


Handling Events 


An event is a report of either a change in the state of a device (such as a 
mouse) or the execution of a routine called by a client. An event can be 
either unsolicited or solicited. Typically, unsolicited events are reports of 
keyboard or pointer activity. Solicited events are Xlib responses to calls by 
clients. 


Xlib reports events asynchronously. When any event occurs, Xlib processes 
the event and sends it to clients that have specified an interest in that 
type of event. 


This chapter describes the following concepts needed to manage events: 
e Event processing—An overview of types of events 


e Event type selection—A description of how clients can specify the types 
of events Xlib reports to them 


e Event handling—A description of handling specific types of events 





Event Processing 


Apart from errors, which Section 9.18 describes, Xlib events issue from 
operations on either windows or pixmaps. Most events result from 
operations associated with windows. The smallest window that contains 
the pointer when a window event occurs is the source window. 


Xlib searches the window hierarchy upward from the source window until 
one of the following applies: 


e Xlib finds a window that one or more clients has identified as 
interested in the event. This window is the event window. After 
Xlib locates an event window, it sends information about the event to 
appropriate clients. 


e Xlib finds a window whose X$L_SWDA_DO_NOT_PROPAGATE 
attribute has been set by a client. Setting this attribute specifies 
that Xlib should not notify ancestors of the window owned by the 
client of events occurring in the window and its children. For more 
information about the X$L_SWDA_DO_NOT_PROPAGATE attribute, 
see Chapter 3. 


¢ Xlib reaches the top of the window hierarchy without finding a window 
that a client has identified as interested in the event. In this case, the 
event is not sent. 


While there are many types of window events, events associated with 
pixmaps occur only when a client cannot compute a destination region 
because the source region is out of bounds (see Chapter 6 for a description 
of source and destination regions). When a client attempts an operation 
on an out of bounds pixmap region, Xlib puts the event on the event queue 
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and checks a list to determine if a client is interested in the event. Ifa 
client is interested, Xlib sends information to the client using an event 


data structure. 


Xlib can report 30 types of events related to keyboards, mice, windowing, 
and graphics operations. A flag identifies each type to facilitate referring 
to the event. Table 9-1 lists event types, grouped by category, and the 


flags that represent them. 


Table 9—1 Event Types 


Event Type 
Keyboard Events 


Key press 
Key release 


Pointer Motion Events 


Button press 
Button release 
Motion notify 


Window Crossing Events 


Enter notify 
Leave notify 


Input Focus Events 


Focus in 
Focus out 


Keymap State Event 


Keymap notify 


Exposure Events 


Expose 
Graphics expose 
No expose 
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Flag Name 


x$c_key_press 
x$c_key_release 


x$c_button_press 
x$c_button_release 
x$c_motion_notify 


x$c_enter_notify 
x$c_leave_notify 


x$c_focus_in 
x$c_focus_out 


x$c_keymap_notify 


x$c_expose 
x$c_graphics_expose 
x$c_no_expose 
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Table 9-1 (Cont.) Event Types 
Event Type Flag Name 


Data Structure Control Events 


Circulate request x$c_circulate_request 
Configure request x$c_configure_request 
Map request x$c_map_request 
Resize request x$c_resize_request 


Window State Events 


Circulate notify x$c_circulate_notify 
Configure notify x$c_configure_notify 
Create notify x$c_create_notify 
Destroy notify x$c_destroy_notify 
Gravity notify x$c_gravity_notify 
Map notify x$c_map_notify 
Mapping notify x$c_mapping_notify 
Reparent notify x$c_reparent_notify 
Unmap notify x$c_unmap_notify 
Visibility notify x$c_visibility_notity 


Color Map State Events 


Color map notify x$c_colormap_notify 


Client Communication Events 


Client message x$c_client_message 
Property notify x$c_property_notify 
Selection clear x$c_selection_clear 
Selection notify x$c_selection_notify 
Selection request x$c_selection_request 


Every event type has a corresponding data structure that Xlib uses to pass 
information to clients. See the sections that describe handling specific 
event types for a description of the relevant event-specific data structures. 


Xlib includes the any event data structure, which clients can use to receive 
reports of any type of event. Figure 9-1 illustrates the data structure. 
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Figure 9-1 Any Event Data Structure 













x$l_anyv_type 


Table 9-2 describes members of the data structure. 
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Table 9-2 Any Event Data Structure Members 


Member Name Contents 


X$L_ANYV_TYPE Type of event Xlib is reporting 
X$L_ANYV_SERIAL Number of the last request processed by the server 


X$L_ANYV_SEND_EVENT Value defined by the constant true if the event came 
from a SEND EVENT request 


X$A_ANYV_DISPLAY Display on which the event occurred 
X$L_ANYV_WINDOW Window in which the event occurred 


To enable clients to manage multiple types of events easily, Xlib also 
includes an event data structure, which is composed of the union 

of individual event data structures. Figure 9-2 illustrates the data 
structure. 


Figure 9-2 Event Data Structure 


x$l_evnt_type 


variable event data, depending upon x$l_evnt_type (92 bytes) 





The X$L_EVNT_TYPE member specifies the type of event being reported. 
For descriptions of the other members of the event data structure, see the 
section that describes the specific event. 
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Selecting Event Types 


Xlib sends information about an event only to clients that have specified 
an interest in that event type. Clients use one of the following methods to 
indicate interest in event types: 


By calling the SELECT INPUT routine. SELECT INPUT indicates to 
Xlib which events to report. 


By specifying event masks when creating a window. 
By specifying event masks when changing window attributes. 


By specifying the graphics exposure mask when creating the graphics 
context. For more information about specifying a graphics exposure 
mask, see Chapter 4. 


Note that Xlib always reports client messages, mapping notifications, 
selection clearings, selection notifications, and selection requests. 


See the description of the SELECT INPUT routine in the VMS 
DECwindows Xlib Routines Reference Manual for restrictions on event 
reporting to multiple clients. 


Using the SELECT INPUT Routine 


Use the SELECT INPUT routine to specify the types of events Xlib reports 
to a client. Select event types by passing to Xlib one or more of the masks 
listed in Table 9-3. 


Table 9-3 Event Masks 


Event Mask 


- x$m_button_motion 


x$m_button1_motion 
x$m_button2_motion 
x$m_button3_motion 
x$m_button4_ motion 
x$m_button5_motion 
x$m_button__press 
x$m_button_release 
x$m_colormap_change 
x$m_enter_window 
x$m_exposure 


x$m_leave_window 


Event Reported (Event Type) 

At least one button on the pointing device is pressed while the pointer moves 
(x$c_motion_notify). 

Pointing device button 1 is pressed while the pointer moves (x$c_motion_notify). 
Pointing device button 2 is pressed while the pointer moves (x$c_motion_notify). 
Pointing device button 3 is pressed while the pointer moves (x$c_motion_notify). 
Pointing device button 4 is pressed while the pointer moves (x$c_motion_notify). 
Pointing device button 5 is pressed while the pointer moves (x$c_button_press). 
Any pointing device button is pressed (x$c_button_press). 

Any pointing device button is released (x$c_button_release). 

A client installs, changes, or removes a color map (x$c_colormap_notify). 

The pointer enters a window (x$c_enter_notify). 


A window becomes visible, a graphics region cannot be computed, a graphics 
request exposes a region, or all source available and a no expose generated 
(x$c_expose, x$c_graphics_expose, x$c_graphics_noexpose). 


The pointer leaves a window (x$c_leave_notify). 
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Table 9-3 (Cont.) Event Masks 


Event Mask 


x$m_focus_change 
x$m_keymap_state 
x$m_key_press _ 
x$m_owner_grab_button 
x$m_pointer_motion 
x$m_pointer_motion_hint 


x$m_property_change 


x$m_structure_notify 


x$m_substructure_notify 


x$m_visibility_change 


9-6 


Event Reported (Event Type) 


The keyboard focus changes (x$c_focus_in, x$c_focus_out). 
The key map changes (x$c_keymap_notify). 

A key is pressed or released (x$c_key "press, x$c_key_release). 
Not applicable. 
The pointer moves (x$c_motion_notify). 


Xlib is free to report only one pointer-motion event (x$c_motion_notify) until one of 
the following occurs: 


¢ Either the key or button state changes. 
¢ The pointer leaves the window. 
¢ The client calls QUERY POINTER or GET MOTION EVENTS. 


A client changes a property (x$c_property_notify). 
One of the following operations occurs on a window: 


¢ Circulate (x$c_circulate_notify) 

¢ Configure (x$c_configure_notify) 
¢ Destroy (x$c_destroy_notify) 

¢ Move (x$c_gravity_notify) 

¢ Map (x$c_map_notify) 

¢ Reparent (x$c_reparent_notify) 
¢ Unmap (x$c_unmap_notify) 


One of the following operations occurs on the child of a window: 


¢ Circulate (x$c_circulate_notify) 

¢ Configure (x$c_configure_notify) 
* Create (x$c_create_notify) 

¢ Destroy (x$c_destroy_notify) 

* Move (x$c_gravity_notify) 

¢ Map (x$c_map_notify) 

¢ Reparent (x$c_reparent_notify) 
¢ Unmap (x$c_unmap_notify) 


The visibility of a window changes (x$c_visibility_notify). 


The following illustrates using the SELECT INPUT routine: 


CALL X$SELECT_INPUT(DPY, WINDOW, X$M_STRUCTURE_NOTIFY) 


Clients specify the x$m_structure_notify mask to indicate an interest in 
one or more of the following window operations (see Table 9-3): 


Circulating Configuring 
Destroying . Reparenting 


Changing gravity Mapping and unmapping 
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9.2.2 Specifying Event Types When Creating a Window 


To specify event types when calling the CREATE WINDOW routine, 
use the method described in Section 3.2.2 for setting window attributes. 
Indicate the type of event Xlib reports to a client by doing the following: 


1 Set the X$L_SWDA_EVENT_MASK window attribute to one or more 
masks listed in Table 9-3. 


2 Specify the event mask flag in the value_mask argument of the 
CREATE WINDOW routine. 


Example 9-1 illustrates this method of selecting events. The program 
specifies that Xlib notify the client of a exposure events. 


Example 9-1 Selecting Event Types Using the CREATE WINDOW Routine 


Qqaaqan 


INTEGER*4 WINDOW 1 


PARAMETER WINDOW_W = 400, WINDOW_H = 300 


Create the WINDOW_1 window 


WINDOW_1X 
WINDOW_1Y 


DEPTH = X$DEFAULT_DEPTH_OF_SCREEN (SCREEN): 
CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 
ATTR_MASK = X$M_CW_EVENT MASK .OR. X$M_CW_BACK_ PIXEL 


(X$WIDTH_OF_SCREEN(SCREEN) - WINDOW lw) / 2 
(X$HEIGHT OF SCREEN(SCREEN) - WINDOW_1H) / 2 


XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE .OR. X$M_BUTTON PRESS 
-XSWDA.X$L_SWDA_BACKGROUND PIXEL = 
1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 1) 


WINDOW_1 = X$CREATE WINDOW (DPY, 

1 X$ROOT_WINDOW_OF_SCREEN (SCREEN) , 

1 WINDOW 1X, WINDOW _1Y, WINDOW_1W, WINDOW_1H, 0, 

1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


@ Set the event mask of the set window attributes data structure to 
indicate interest in exposure events. 


| @ The window attribute is referred to by ATTR_MASK, which specifies 
the attribute. 


9.2.3 Specifying Event Types When Changing Window Attributes 


To specify one or more event types when changing window attributes, 
use the method described in Section 3.6 for changing window attributes. 
Indicate an interest in event types by doing the following: 


1 Set the X$L_SWDA_EVENT_MASK window attribute to one or more 
masks listed in Table 9-3. 


2 Specify the event mask flag using the value_mask argument of the 
CHANGE WINDOW ATTRIBUTES routine. 
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The following illustrates this method: 


ATTR_MASK = X$M_STRUCTURE_NOTIFY 
CALL X$CHANGE_WINDOW_ ATTRIBUTES (DPY, WINDOW, ATTR_MASK, XSWA) 


Pointer Events 





Xlib reports pointer events to interested clients when the button on the 
pointing device is pressed or released, or when the pointer moves. 


This section describes how to handle the following pointer events: 
¢ Pressing a button on the pointing device 

¢ Releasing a button on the pointing device 

¢ Moving the pointing device 


The section also describes the button event and motion event data 
structures. 


Handling Button Presses and Releases 


To receive event notification of button presses and releases, pass the 
window identifier and either the x$m_button_press or the x$m_button_ 
release mask when using the selection method described in Section 9.2. 


When a button is pressed, Xlib searches for ancestors of the event window 
from the root window down to determine whether or not a client has 
specified a passive grab, an exclusive interest in the button. If Xlib finds 
no passive grab, it starts an active grab, reserving the button for the 
sole use of the client receiving notification of the event. Xlib also sets the 
time of the last pointer grab to the current server time. The effect is the 
same as calling the GRAB BUTTON routine with argument values listed 
in Table 9-4. 


Table 9-4 Values Used for Grabbing Buttons 


Argument Value 

window_id : Event window. 

event_mask Client pointer motion mask. 

pointer_mode The value specified by the constant x$c_grab_mode_async. 
keyboard_mode The value specified by the constant x$c_grab_mode_async. 
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Table 9-4 (Cont.) Values Used for Grabbing Buttons 


Argument Value 

owner_events True, if the owner has specified x$m_owner_grab_button. 
Otherwise, false. 

confine_to None. 

cursor None. 





Xlib terminates the grab automatically when the button is released. 
Clients can modify the active grab by calling the UNGRAB POINTER and 
CHANGE ACTIVE POINTER GRAB routines. 


Xlib uses the button event data structure to report button presses and 
releases. Figure 9-3 illustrates the data structure. 


Figure 9-3 Button Event Data Structure 
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Table 9-5 describes members of the button event data structure. 


Table 9-5 Button Event Data Structure Members 


Member Name 


X$L_BTEV_TYPE 


X$L_BTEV_SERIAL 
X$L_BTEV_SEND_EVENT 


X$A_BTEV_DISPLAY 
X$L_BTEV_WINDOW 
X$L_BTEV_ROOT 
X$L_BTEV_SUBWINDOW 
X$L_BTEV_TIME 
X$L_BTEV_X 


X$L_BTEV_Y 


X$L_BTEV_X_ROOT 
X$L_BTEV_Y_ROOT 
X$L_BTEV_STATE 


X$L_BTEV_BUTTON 


Contents 

Type of event reported. The event type can be either x$c_button_press or 
x$c_button_release. 

Number of the last request processed by the server. 


Value defined by the constant true if the event came from a SEND EVENT 
request. 


Display on which the event occurred. 

Event window. 

Root window in which the event occurred. 
Source window in which the event occurred. 
Time in milliseconds at which the event occurred. 


The x value of the pointer coordinates in the source window at the time the 
event occurred. 


The y value of the pointer coordinates in the source window at the time the 
event occurred. 


The x value of the pointer coordinates, relative to the root window. 
The y value of the pointer coordinates, relative to the root window. 


State of the button just prior to the event. Xlib can set this member to the 
bitwise OR to one or more of the following masks: 


x$m_buitton1 x$m_button2 
x$m_button3 x$m_button4 
x$m_button5 x$m_mod1 
x$m_mod2 x$m_mod3 
x$m_mod4 x$m_mod5 


Buttons that changed state. Xlib can set this member to one of the 
following values: 


x$c_button1 x$c_button2 
x$c_button3 x$c_button4 
x$c_button5 
X$L_BTEV_SAME_SCREEN Indicates whether or not the event window is on the same screen as the 
root window. 
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Example 9-2 illustrates the button press event handling routine of the 
sample program described in Chapter 1. 


The program calls shutdown routines when the user presses the mouse 
button in WINDOW_2. When creating WINDOW_1 and WINDOW_2, the 
client indicated an interest in exposures and button presses by setting the 
event mask field of the set window attributes data structure, as follows: 
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Example 9-2 Handling Button Presses 


IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON_PRESS) THEN 
IF (EVENT.EVNT_EXPOSE.X$L_EXEV_ WINDOW .EQ. WINDOW_1) THEN 
STATE = 2 
CALL X$DRAW_IMAGE STRING (DPY, WINDOW_2, GC, 
1 75, 75, MESSAGE (STATE) ) 
ELSE 


CALL XS$UNMAP_WINDOW(DPY, WINDOW_1) 
CALL XSDESTROY_WINDOW(DPY, WINDOW_1) 
CALL X$CLOSE_DISPLAY (DPY) 
CALL SYSSEXIT (%VAL (1) ) 
END IF 
END IF 


RECORD /X$SET_WIN_ATTRIBUTES/ XSWDA 


XSWDA.X$L_SWDA_EVENT_MASK = X$M_CW_EVENT_MASK 
.OR. X$M_CW BUTTON PRESS 


For more information about selecting event types, see Section 9.2. 


9.3.2 Handling Pointer Motion 


To only receive pointer motion events when a specified button is pressed, 
pass the window identifier and one of the following masks when using the 
selection method described in Section 9.2: 


x$m_button_motion x$m_button1_motion 

x$m_button2_motion § x$m_button3_motion 

x$m_button4_motion § x$m_button5_motion 

Xlib reports pointer motion events to interested clients whenever the 
pointer moves and the movement begins and ends in the window. Spatial 
and temporal resolution of the events is not guaranteed, but clients are 
assured they will receive at least one event when the pointer moves and 


then rests. Figure 9-4 illustrates the data structure Xlib uses to report 
these events. 


o-11 


Handling Events 
9.3 Pointer Events 


Figure 9-4 Motion Event Data Structure 


x$l_mtev_type 


x$l_mtev_y 
x$l_mtev_x_root 
x$l_mtev_y_root 


x$l_mtev_state 


sof x$l_mtev_same_screen x$b_mtev_is_hint 


x$l_mtev_same_screen : 


x$l_mtev_x 





Table 9-6 describes members of the data structure. 


Table 9-6 Motion Event Data Structure Members 





Member Name Contents 

X$L_MTEV_TYPE Type of event reported. The member can have only the value specified by the 
constant x$c_motion_notify. 

X$A_MTEV_DISPLAY Display on which the event occurred. 

X$L_MTEV_SERIAL Number of the last request processed by the server. 

X$L_MTEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. . 

X$L_MTEV_WINDOW Event window. 

X$L_MTEV_ROOT . Root window in which the event occurred. 

X$L_MTEV_SUBWINDOW Source window in which the event occurred. 
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Table 9-6 (Cont.) Motion Event Data Structure Members 


Member Name 


X$L_MTEV_TIME 
X$L_MTEV_X 
X$L_MTEV_Y 
X$L_MTEV_X_ROOT 
X$L_MTEV_Y_ROOT 
X$L_MTEV_STATE 


X$B_MTEV_IS_HINT 


X$L_MTEV_SAME_SCREEN 


Contents 


Time in milliseconds at which the event occurred. 

The x value of the pointer coordinates in the source window. 

The y value of the pointer coordinates in the source window. 

The x value of the pointer coordinates relative to the root window. 
The y value of the pointer coordinates relative to the root window. 


State of the button just prior to the event. Xlib can set this member to the 
bitwise OR to one or more of the following masks: 


x$m_button1 x$m_button2 
x$m_button3 x$m_button4 
x$m_button5 x$m_mod1 
x$m_mod2 x$m_mod3 
x$m_mod4 x$m_mod5 


Indicates that motion hints are active. No other events reported until pointer 
moves out of window. 

Indicates whether or not the event window is on the same screen as the root 
window. 


Example 9-3 illustrates pointer motion event handling. 


Example 9-3 Handling Pointer Motion 





IF (EVENT.EVNT_ TYPE .EQ. X$C_MOTION_NOTIFY) THEN 


xX 
Y 


EVENT .EVNT_MOTION.X$L_MTEV_X 
EVENT .EVNT_MOTION.X$L_MTEV_Y 


CALL X$FILL_RECTANGLE (DPY, WINDOW, GC, X, Y, WIDTH, LENGTH) 


ENDIF 





Each time the pointer moves, the program draws a filled rectangle at the 
resulting x and y coordinates. 


To receive pointer motion events, the client specifies the x$c_motion_ 
notify flag when removing events from the queue. The client indicated 
an interest in pointer motion events when creating window WINDOW, as 
follows: 


XSWDA.X$L_SWDA_EVENT MASK = X$M_EXPOSURE 
1 .OR. X$M_BUTTON PRESS | 
if .OR. X$M POINTER MOTION 


XSWDA.X$L_SWDA_BACKGROUND PIXEL = 
1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 1) 
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WINDOW = X$CREATE_WINDOW(DPY, 

1  X$ROOT_WINDOW_OF_ SCREEN (SCREEN) , 

1  WINDOW_X, WINDOW_Y, WINDOW_W, WINDOW_H, 0, 

1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


The server reports pointer movement. Xlib records the resulting position 
of the pointer in a motion data structure, one of the event structures that 
constitute the event structure. The client determines the origin of the 
filled rectangle it draws by referring to the motion event data structure 

x and y members. 





Key Events 


Xlib reports key press and key release events to interested clients. To 
receive event notification of key presses and releases, pass the window 
identifier and either the x$m_key_press mask or the x$m_key_release 
mask when using the selection method described in Section 9.2. 


Xlib uses a key event data structure to report key presses and releases to 
interested clients whenever any key changes state, even when the key is 
mapped to modifier bits. 


Figure 9-5 illustrates the data structure. 


Figure 9-5 Key Event Data Structure 














x$l_kyev_type 0 

; 
2 
? 
: 
, 
: 
: 
: 
: 
x$l_kyev_y_root 44 

: 





(continued on next page) 
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Figure 9-5 (Cont.) Key Event Data Structure 






: 
: 
Table 9-7 describes members of the data structure. 

Table 9-7 Key Event Data Structure Members 
Member Name Contents 
X$L_KYEV_TYPE Value defined by either the x$c_key _press or the x$c_key_release constant. 
X$L_KYEV_SERIAL Number of the last event processed by the server. 
X$L_KYEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 
X$A_KYEV_DISPLAY Display on which the event occurred. 
X$L_KYEV_WINDOW Event window. 
X$L_KYEV_ROOT Root window on which the event occurred. 
X$L_KYEV_SUBWINDOW Source window of the event. 
X$L_KYEV_TIME Time in milliseconds at which the key event occurred. 
X$L_KYEV_X The x value of the pointer coordinates in the source window. 
X$L_KYEV_Y The y value of the pointer coordinates in the source window. 
X$L_KYEV_X_ROOT The x value of the pointer coordinates relative to the root window. 
X$L_KYEV_Y_ROOT The y value of the pointer coordinates relative to the root window. 
X$L_KYEV_STATE State of the key just prior to the key event. Xlib can set this member to the 
bitwise OR of the following states: 
x$m_shift x$m_lock 
x$m_control x$m_mod1 
x$m_mod2 x$m_mod3 
x$m_mod4 x$m_mod5 
X$L_KYEV_KEYCODE An arbitrary but unique representation of the key that generated the event. 
X$L_KYEV_SAME_SCREEN Indicates whether the event window is on the same screen as the root window. 





Window Entries and Exits 


Xlib reports window entries and exits to interested clients when one of the 
following occurs: 


¢ The pointer moves into or out of a window due to either pointer 
movement or to a change in window hierarchy. This is normal window 
entry and exit. 


¢ Actlient calls WARP POINTER, which moves the pointer to any 
specified point on the screen. 
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e A client calls CHANGE ACTIVE POINTER GRAB, GRAB 
KEYBOARD, GRAB POINTER, or UNGRAB POINTER. This is 
pseudomotion, which simulates window entry or exit without actual 
pointer movement. . 


To receive event notification of window entries and exits, pass the window 
identifier and either the x$m_enter_window mask or the x$m_leave_ 
window mask when using the selection method described in Section 9.2. 


Xlib uses the crossing event data structure to report window entries and 
exits. Figure 9-6 illustrates the data structure. 


Figure 9-6 Crossing Event Data Structure 
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Table 9-8 describes members of the data structure. 


Table 9-8 Crossing Event Data Structure Members 





Member Name 


X$L_CREV_TYPE 


X$L_CREV_SERIAL 
X$L_CREV_SEND_EVENT 


X$A_CREV_DISPLAY 
X$L_CREV_WINDOW 
X$L_CREV_ROOT 
X$L_CREV_SUBWINDOW 
X$L_CREV_TIME 
X$L_CREV_X 
X$L_CREV_Y 
X$L_CREV_X_ROOT 
X$L_CREV_Y_ROOT 
X$L_CREV_MODE 


X$L_CREV_DETAIL 


X$L_CREV_SAME_SCREEN 


X$L_CREV_FOCUS 


X$L_CREV_STATE 


Contents 


Value defined by either the x$c_enter_notify or the x$c_leave_notify 
constant. 


Number of the last request processed by the server. 


Value defined by the constant true if the event came from a SEND EVENT 
request. 


Display on which the event occurred. 

Event window. 

Root window in which the event occurred. 

Source window in which the event occurred. 

Time in milliseconds at which the event occurred. 

The x value of the pointer coordinates in the source window. 

The y value of the pointer coordinates in the source window. 

The x value of the pointer coordinates relative to the root window. 
The y value of the pointer coordinates relative to the root window. 


Indicates whether the event is normal or pseudomotion. Xlib can set this 
member to the value specified by x$c_notify_normal, x$c_notify_grab, and 
x$c_notify_ungrab. See Section 9.5.1 and Section 9.5.2 for descriptions of 
normal and pseudomotion events. 

Indicates which windows Xlib notifies of the window entry or exit event. 
Xlib can specify in this member one of the following constants: 
x$c_notify_ancestor x$c_notify_virtual 

x$c_notify_inferior x$c_notify_nonlinear 
x$c_notify_nonlinear_virtual 

Indicates whether or not the event window is on the same screen as the 
root window. 

Specifies whether the event window or an inferior is the focus window. If 
true, the event window is the focus window. If false, an inferior is the focus 
window. 

State of buttons and keys just prior to the event. Xlib can return the 
following constants: 


x$m_button1 x$m_button2 
x$m_button3 x$m_button4 
x$m_button5 x$m_mod1 
x$m_mod2 x$m_mod3 
x$m_mod4 x$m_mod5 
x$m_shift x$m_control 
x$m_lock 
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Normal Window Entries and Exits 


A normal window entry or exit event occurs when the pointer moves from 
one window to another due to either a change in window hierarchy or the 
movement of the pointer. In either case, Xlib sets the X$L_CREV_MODE 
member of the crossing event data structure to the constant x$c_notify_ 
normal. 


If the pointer leaves or enters a window as a result of one of the following 
changes in window hierarchy, Xlib reports the event after reporting the 
hierarchy event: 


Mapping Unmapping 
Configuring Circulating 
Changing gravity 


Xlib can report a window entry or exit event caused by changes in focus, 
visibility, and exposure either before or after reporting these events. 


Table 9-9 describes the events Xlib reports when the pointer moves from 
window A to window B as a result of normal window entry or exit. 


Table 9-9 Normal Window Entry and Exit Event Reporting 


Relationship of Windows 


Events Reported 


Window A is inferior to window B A leave notify event on window A with the X$L_CREV_DETAIL 


member of the crossing event data structure set to the constant 
x$c_notify_ancestor 

A leave notify event on each window between window A and 
window B exclusive, with the X$L_CREV_DETAIL member of each 
crossing event data structure set to the constant x$c_notify_virtual 


An enter notify event on window B with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_inferior 


Window B is inferior of window A A leave notify event on window A with the X$L_CREV_DETAIL 


member of the crossing event data structure set to the constant 
x$c_notify_inferior 

An enter notify event on each window between window A and 
window B exclusive with the X$L_CREV_DETAIL member of each 
crossing event data structure set to the constant x$c_notify_virtual 


An enter notify event on window B with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_ancestor 
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Table 9-9 (Cont.) Normal Window Entry and Exit Event Reporting 


Relationship of Windows 


Window C is the least common ancestor of 
AandB 


Window A and window B are on different 
screens 


Events Reported 


A leave notify event on window A with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_nonlinear 

A leave notify event on each window between window A and 
window C exclusive with the X$L_CREV_DETAIL member of 
the crossing event data structure set to the constant x$c_notify_ 
nonlinear_virtual 

An enter notify event on each window between window C and 
window B exclusive with the X$L_CREV_DETAIL member of 
each crossing event data structure set to the constant x$c_notify_ 
nonlinear_virtual 

An enter notify event on window B with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_nonlinear 

A leave notify event on window A with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_nonlinear 

If window A is not a root window, a leave notify event on each 
window above window A up to and including its root, with the 
X$L_CREV_DETAIL member of each crossing event data structure 
set to the constant x$c_notify_nonlinear_virtual 


if window B is not a root, an entry notify event on each window 
from window B’s root down to but not including window B, with the 
X$L_CREV_DETAIL member of the crossing event data structure 
set to the constant x$c_notify_nonlinear_virtual 

An enter notify event on window B with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_nonlinear 





Example 9—4 illustrates window entry and exit event handling. The 
program changes the color of a window when the pointer enters or leaves 


the window. 


Figure 9-7 shows the resulting output. 
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Example 9—4 Handling Window Entries and Exits 





Cc 


Create windows WINDOW, SUB1, SUB2, 
SUB3, and SUB4 on display DPY. 
Position of WINDOW is: x = 100,y = 100 


PARAMETER WINDOW_W = 600, WINDOW_H = 600, 


PPP RP 


SUB_WIDTH = 120, SUB_HEIGHT= 120, 


SUB1_X = 120, SUB1_Y = 120, 
SUB2_X = 360, SUB2_Y = 120, 
SUB3_X = 120, SUB3_Y = 360, 
SUB4_X = 360, SUB4 Y = 360 


IF (EVENT.EVNT_TYPE .EQ. X$C_ENTER_NOTIFY) THEN 


CROSS WINDOW = EVENT.EVNT_CROSSING.X$L_CREV_WINDOW 
CALL X$SET_WINDOW BACKGROUND (DPY, CROSS_WINDOW, 
DEFINE _COLOR(DPY, SCREEN, VISUAL, 3)) 


CALL X$CLEAR_AREA(DPY, CROSS_WINDOW, 0, 0, SUB_WIDTH, 
SUB_HEIGHT, 0) 
END IF 


IF (EVENT.EVNT_TYPE .EQ. X$C_LEAVE NOTIFY) THEN 
CROSS WINDOW = EVENT.EVNT_CROSSING.X$L_CREV_WINDOW 
CALL X$SET_WINDOW_BACKGROUND (DPY, CROSS_WINDOW, 
DEFINE_COLOR(DPY, SCREEN, VISUAL, 2)) 
CALL X$CLEAR_AREA(DPY, CROSS_WINDOW, 0, 0, SUB_WIDTH, 
SUB_HEIGHT, 0) 
END IF 
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@ Xilib gives the identifier of the window that the pointer cursor has 
entered in the crossing event data structure window field. The 
program uses the identifier to define the window background and 
clear the window. 


@ The CLEAR AREA routine clears the window and repaints it with the 
newly defined window background. 
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Figure 9-7 Window Entries and Exits 
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Subwindows turn gray when pointer cursor is in them. 


To exit, click MB2. 
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9.5.2 Pseudomotion Window Entries and Exits 


Pseudomotion window entry and exit events occur when the pointer cursor 
moves from one window to another due to activating or deactivating a 
pointer grab. 


Xlib reports a pseudomotion window entry if a client grabs the pointer, 
causing the pointer cursor to change from one window to another even 
though the pointer cursor has not moved. For example, if the pointer 
cursor is in window A and a client maps window B over window A, the 
pointer cursor changes from being in window A to being in window B. If 
possible, the pointer cursor remains in the same position on the screen. 
When the placement of the two windows prevents the pointer cursor from 
maintaining the same position, the pointer cursor moves to the location 
closest to its original position. 
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Clients can grab pointers actively by calling the GRAB POINTER routine 
or passively by calling the GRAB BUTTON routine. Whether the grab is 
active or passive, Xlib sets the following members of the crossing event 
data structure to the indicated constants after the pointer cursor moves 
from one window to another: 


¢ X$L_CREV_TYPE member—x$c_enter_notify 
¢ X$L_CREV_MODE member—x$c_notify_grab 


When a client passively grabs the pointer by calling the GRAB BUTTON 
routine, Xlib reports a button press event after reporting the pointer grab. 


Xlib reports a pseudomotion window exit when a client deactivates a 
pointer grab, causing the pointer cursor to change from one window to 
another even though the pointer cursor has not moved. 


Clients can deactivate pointer grabs either actively by calling the 
UNGRAB POINTER routine or passively by calling the UNGRAB 
BUTTON routine. Whether deactivating the grab is active or passive, 
Xlib sets the following members of the crossing event data structure to 
the indicated constants after the pointer cursor moves from one window to 
another: 


e X$L_CREV_TYPE member—x$c_leave_notify 
e X$L_CREV_MODE member—x$c_notify_ungrab 
When a client passively deactivates a pointer grab by calling the UNGRAB 


BUTTON routine, Xlib reports a button release event before reporting that 
the pointer has been released. 





9.6 Input Focus Events 
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Input focus defines the window to which Xlib sends keyboard input. The 
keyboard is always attached to some window. Typically, keyboard input 
goes to either the root window or to a window at the top of the stack called 
the focus window. The focus window and the position of the pointer 
determine the window that receives keyboard input. 


When the keyboard input focus changes from one window to another, Xlib 
reports a focus out event and a focus in event. The window that loses the 
input focus receives the focus out event. The window that gains the focus 
receives a focus in event. Additionally, Xlib notifies other windows in the 
hierarchy of focus in and focus out events. 


To receive notification of input focus events, pass the window identifier and 
the x$m_focus_change mask when using the selection method described 
in Section 9.2 


Xlib uses the focus change event data structure to report keyboard input 
focus events. Figure 9-8 illustrates the data structure. 
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Figure 9-8 Focus Change Event Data Structure 
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Table 9—10 describes members of the data structure. 


Table 9-10 Focus Change Event Data Structure Members 


Member Name Contents 

X$L_FCEV_TYPE Value defined by either the x$c_focus_in or x$c_focus_out constant. 

X$L_FCEV_SERIAL Number of the last request processed by the server. 

X$L_FCEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 

X$A_FCEV_DISPLAY Display on which the event occurred. 

X$L_FCEV_WINDOW Event window. 

X$L_FCEV_MODE Specifies whether the event is the result of normal keyboard input, keyboard 


input after a client has grabbed the keyboard, keyboard input at the time 

the client activates a keyboard grab, or keyboard input at the time the client 
deactivates a keyboard grab. 

Xlib can set this field to one of the following constants: 

x$c_notify_normal x$c_notify_while_grabbed 

x$c_notify_grab x$c_notify_ungrab 

See Section 9.6.1 and Section 9.6.2 for descriptions of processing input focus 
events in each of these conditions. 


X$L_FCEV_DETAIL Specifies which windows and pointers Xlib notifies of the input focus change. 
Xlib can set this field to one of the following constants: 
x$c_notify_ancestor x$c_notify_virtual 
x$c_notify_inferior x$c_notify_nonlinear 
x$c_notify_nonlinear_virtual x$c_notify_pointer 
x$c_notify_pointer_root x$c_notify_detail_none 
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Normal Keyboard Input Focus 


A normal keyboard input focus event occurs when keyboard input focus 
changes, and the keyboard has not been or is not being grabbed. When 
a normal keyboard input focus event occurs, Xlib sets the X$L_FCEV_ 
MODE member of the focus change event data structure to the constant 
x$c_notify_normal. 


Table 9-11 lists focus change events reported when window A and window 
B are on the same screen, the focus changes from window A to window B, 
and the pointer cursor is in window P. 


Table 9-11 Effect of Focus Changes: Windows on Same Screen 





Window A Inferior to Window B 





Window Event Reported Value of X$L_FCEV_DETAIL 
Window A Focus out event x$c_notify_ancestor 

Window B Focus in event x$c_notify_inferior 

Window P Focus in event on each window between x$c_notify_inferior 


window B and window P including P if 
window P is an inferior of window B, but 
window P is not window A or an inferior of A 


Other windows". Focus out event on each window between x$c_notify_virtual 
window A and window B exclusive 





Window B Inferior to Window A 





Window Event Reported Value of X$L_FCEV_DETAIL 
Window A Focus out event x$c_notify_inferior 

Window B Focus in event x$c_notify_ancestor 

Window P Focus out event on each window between x$c_notify_pointer 


window P and window A if window P is an 
inferior of window A, but window P is not 
window A or an inferior or ancestor of B 


Other windows Focus in event on each window between x$c_notify_virtual 
window A and window B exclusive 





Table 9-12 lists focus change events reported when the pointer cursor 
moves from window A to window B and window C is their least common 
ancestor. The pointer cursor is in window P. 


" 
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Table 9-12 Focus Changes Caused by Pointer Movement 


Pointer Moves from Window A to Window B 





Window Event Reported Value of X$L_FCEV_DETAIL 
Window A Focus out event x$c_notify_nonlinear 

Window B Focus in event x$c_notify_nonlinear 

Window P If window P is an inferior of window A, but x$c_notify_pointer 


window P is not window A or an inferior 
or ancestor of B, a focus out event on 
each window from window P up to but not 
including window A 


If window P is an inferior of window B, x$c_notify_pointer 
a focus in event on each window below 
window B down to and including window P 


Other windows Focus out event on each window between x$c_notify_nonlinear_virtual 
window A and window C exclusive 
Focus in event on each window between x$c_notify_nonlinear_virtual 


window C and window B exclusive 


Table 9-13 lists focus change events reported when window A and window 
B are on different screens and the focus changes from window A to window 
B. The pointer cursor is in window P. 


Table 9-13 Effect of Focus Changes: Windows on Different Screens 





Focus Changes from Window A to Window B 


Window Event Reported Value of X$L_FCEV_DETAIL 
Window A Focus out event x$c_notify_nonlinear 

Window B Focus in event . x$c_notify_nonlinear 

Window P lf window P is an inferior of window A, x$c_notify_pointer 


a focus out event on each window from 
window P up to but not including window A 


If window P is an inferior of window B, x$c_notify_pointer 
a focus in event on each window below 
window B down to and including window P 


Other windows If window A is not a root window, a focus x$c_notify_nonlinear_virtual 
out event on each window above window A 
up to and including its root 


If window B is not a root window, a focus in x$c_notify_nonlinear_virtual 
event on each window from the root window 
of B down to but not including B 





Table 9-14 lists focus change events reported when the focus changes 
between window A and the pointer window, or when the focus is set to 
none (no focus). 
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Table 9-14 Pointer Window and No Focus Changes 





Focus Changes from Window A to Pointer Window or to No Focus 





Window Event Reported Value of X$L_FCEV_DETAIL 

Window A Focus out event x$c_notify_nonlinear 

All root windows Focus in event x$c_notify_pointer_root or x$c_notify_ 
detail_none 

Window P If window P is an inferior of window A, x$c_notify_pointer 


a focus out event on each window from 
window P up to but not including window A 


Other windows if window A is not a root window, a focus x$c_notify_nonlinear_virtual 
out event on each window above window A 
up to and including its root 


If the new focus is the window under the x$c_notify_pointer_root 
pointer, a focus in event on each window 

from the root of window P down to and 

including window P 





Focus Changes from Pointer Window or No Focus to Window A 
Window Event Reported Value of X$L_FCEV_DETAIL 





Window A Focus in event x$c_notify_nonlinear 

All root windows Focus out event x$c_notify_pointer_root or x$c_notify_ 
detail_none 

Window P If window P is an inferior of window A, x$c_notify_pointer 


a focus in event on each window below 
window A down to and including P 


Focus out event on each window from x$c_notify_pointer_root 
window P up to and including the root of P 

Other windows Focus out event on each window from x$c_notify_pointer_root 
window P up to and including the root of P 
If window A is not a root window, a focus x$c_notify_nonlinear_virtual 


in event on each window from the root of 
window A down to but not including A 





(continued on next page) 
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Table 9-14 (Cont.) Pointer Window and No Focus Changes 


Focus Changes from Pointer Window to No Focus or from No Focus 
to Pointer Window 


Window Event Reported Value of X$L_FCEV_DETAIL 

All root windows Focus out event — x$c_notify_pointer_root or x$c_notify_ 
detail_none 

Old focus window If the old focus was the window under the x$c_notify_pointer_root 


pointer, a focus out event on each window 
from window P up to and including the root 
of P 
New focus window If the new focus is the window under the x$c_notify_pointer_root 
pointer, a focus in event on each window 
from the root of P down to and including P 


Keyboard Input Focus Changes Caused by Grabs 


When a keyboard focus event occurs because a client activates a grab, 
Xlib sets the X$L_FCEV_MOVE member of the focus change event data 
structure to the constant x$c_notify_grab. 


When a keyboard focus event occurs because a client deactivates a grab, 
Xlib sets the X$L_FCEV_MOVE member of the focus change event data 
structure to the constant x$c_notify_ungrab. 





Key Map State Events 


Xlib reports changes in the state of the key map immediately after every 
enter notify and focus in event. 


To receive notification of key map state events, pass the window identifier 
and the x$m_keymap_state mask when using the selection method 
described in Section 9.2. 


Xlib uses the keymap event data structure to report changes in the key 
map state. Figure 9-9 illustrates the data structure. 


Figure 9-9 Keymap Event Data Structure 
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Events 


Figure 9-9 (Cont.) Keymap Event Data Structure 


x$b_kmev_key_vector (32 bytes) 





Table 9-15 describes members of the data structure. 


Table 9-15 Keymap Event Data Structure Members 


Member Name Contents 

X$L_KMEV_TYPE Value defined by the x$c_keymap_notify constant. 

X$L_KMEV_SERIAL Number of the last request processed by the 
server. 

X$L_KMEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_KMEV_DISPLAY Display on which the event occurred. 

X$L_KMEV_WINDOW Event window. 

X$B_KMEV_KEY_VECTOR Bit vector of the keyboard. Each one bit indicates 


that the corresponding key is currently pressed. 
Byte N contains the bits for keys 8N to 8N+7 with 
the least significant bit representing key 8N. 





9.8 Exposure Events 


Xlib reports an exposure event when one of the following conditions occurs: 
e A formerly obscured window or window region becomes visible. 
e A destination region cannot be computed. 


e A graphics request exposes one or more regions. 


This section describes how to handle window exposures and graphics 
exposures. 


9.8.1. Handling Window Exposures 
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A window exposure occurs when a formerly obscured window becomes 
visible again. Because Xlib does not guarantee to preserve the contents of 
regions when windows are obscured or reconfigured, clients are responsible 
for restoring the contents of the exposed window. 


To receive notification of window exposure events, pass the window 
identifier and the x$m_exposure mask when using the selection 
method described in Section 9.2. Xlib notifies clients of window exposures 
using the expose event data structure. Figure 9-10 illustrates the data 
structure. 


‘Handling Events 
9.8 Exposure Events 


Figure 9-10 Expose Event Data Structure 


x$l_exev_type 
x$l_exev_serial 


x$l_exev_send_event 


x$a_exev_display 


x$l_exev_window 
x$l_exev_x 
x$l_exev_y 
_ -x$lLexev_width 
x$l_exev_height 


x$l_exev_count 





Table 9-16 describes members of the data structure. 


Table 9-16 Expose Event Data Structure Members 


Member Name Contents 

X$L_EXEV_TYPE - Value defined by the x$c_expose consiant. 

X$L_EXEV_SERIAL Number of the last request processed by the 
server. 

X$L_EXEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_EXEV_DISPLAY Display on which the event occurred. 

X$L_EXEV_WINDOW Event window. 

X$L_EXEV_X The x value of the coordinates that define the 


upper left corner of the exposed region. The 
coordinates are relative to the origin of the. 
drawable. 


X$L_EXEV_Y The y value of the coordinates that define the 
upper left corner of the exposed region. The 
coordinates are relative to the origin of the 
drawable. 
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Table 9-16 (Cont.) Expose Event Data Structure Members 


Member Name Contents 

X$L_EXEV_WIDTH Width of the exposed region. 
X$L_EXEV_HEIGHT Height of the exposed region. 
X$L_EXEV_COUNT Number of exposure events that are to follow. If 


Xlib sets the count to zero, no more exposure 
events follow for this window. 


Clients that do not optimize redisplay by 
distinguishing between subareas of its windows 
can ignore all exposure events with nonzero 
counts and perform full redisplays on events with 
zero counts. 


The following fragment from the sample program in Chapter 1 illustrates 
window exposure event handling: 


IF (EVENT.EVNT_ TYPE .EQ. X$C_EXPOSE .AND. 
EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW_2) THEN 
CALL X$CLEAR_WINDOW(DPY, WINDOW_2) 

CALL X$DRAW_IMAGE STRING(DPY, WINDOW_2, GC, 


75, 75, ‘Click here to exit’) 


The program checks exposure events to verify that the server has mapped 
the second window. After the window is mapped, the program writes text 
into it. 


9.8.2 Handling Graphics Exposures 


Xlib reports graphics exposures when one of the following conditions 
occurs: 


e A destination region could not be computed due to an obscured or out 
of bounds source region. For information about destination and source 
regions, see Chapter 6. 


e A graphics request exposes one or more regions. If the request exposes 
more than one region, Xlib reports them continuously. 


Instead of using the SELECT INPUT routine to indicate an interest 

in graphics exposure events, assign a value of true to the X$L_GCVL_ 
GRAPHICS_EXPOSURES member of the GC values data structure. 
Clients can set the value to true at the time they create a graphics context. 
If a graphics context exists, use the SET GRAPHICS EXPOSURES 
routine to set the value of the field. For information about creating a 
graphics context and using the SET GRAPHICS EXPOSURES routine, see 
Chapter 4. 


~~ Handling Events 
- 9.8 Exposure Events 


Xlib uses the graphics expose event data structure to report graphics 
exposures. Figure 9-11 illustrates the data structure. 


Figure 9-11 Graphics Expose Event Data Structure 
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Table 9-17 describes members of the data structure. 


Table 9-17 Graphics Expose Event Data Structure Members 


Member Name Contents 

X$L_GEEV_TYPE Value defined by the constant x$c_graphics_ 
expose. 

X$L_GEEV_SERIAL Number of the last request processed by the 
server. 

X$L_GEEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$L_GEEV_DISPLAY Display on which the event occurred. 


X$L_GEEV_DRAWABLE _ Window or pixmap reporting the event. 
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Table 9-17 (Cont.) Graphics Expose Event Data Structure Members 





Member Name . Contents 


X$L_GEEV_X The x value of the coordinates that define the 
upper left corner of the exposed region. The 
coordinates are relative to the origin of the 
drawable. 


X$L_GEEV_Y The y value of the coordinates that define the 
upper left corner of the region that is exposed. 
The coordinates are relative to the origin of the 


drawable. 
X$L_GEEV_WIDTH Width of the exposed region. 
X$L_GEEV_HEIGHT Height of the exposed region. 
X$L_GEEV_COUNT Number of exposure events that are to follow. If 


Xlib sets the count to zero, no more exposure 
events follow for this window. 


X$L_GEEV_MAJOR_CODE Indicates whether the graphics request was a copy 
area or copy plane. 
X$L_GEEV_MINOR_CODE The value zero. Reserved for use by extensions. 


Xlib uses the no expose event data structure to report when a graphics 
request. that might have produced an exposure did not. Figure 9-12 
illustrates the data structure. 


Figure 9-12 No Expose Event Data Structure 
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Table 9-18 describes members of the no expose event data structure. 


Tabie 9-18 No Expose Event Data Structure Members 


Member Name 


X$L_NEEV_TYPE 
X$L_NEEV_SERIAL 


X$L_NEEV_SEND_EVENT 


X$A_NEEV_DISPLAY 
X$L_NEEV_DRAWABLE 
X$L_NEEV_MAJOR_CODE 


X$L_NEEV_MINOR_CODE 


Contents 


Value defined by the constant x$c_no_expose. 


Number of the last request processed by the 
server. 


Value defined by the constant true if the event 
came from a SEND EVENT request. 


Display on which the event occurred. 
Window or pixmap reporting the event. 


Indicates whether the graphics request was a copy 
area or a copy plane. 


The value zero. Reserved for use by extensions. 


Example 9-5 illustrates handling graphics exposure events. The program 
checks for graphics exposures and no exposures to scroll up a window. 


Figure 9-13 shows the resulting output of the program. 


Example 9-5 Handling Graphics Exposures 


aaa 


INTEGER*4 
INTEGER* 4 
INTEGER*4 
INTEGER* 4 
INTEGER* 4 


Handle events 


Y 


PX, PY 
WIDTH, HEIGHT 
BUTTON_IS DOWN 


DO WHILE (.TRUE.) 
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Example 9-5 (Cont.) Handling Graphics Exposures 





CALL X$NEXT_EVENT(DPY, EVENT) 
IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN 
CALL XS$DRAW_IMAGE STRING(DPY, WINDOW, GC, 


1 150, 25, 'To-scroll, press MB1.’) 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 
iL 150, 75, ‘To exit, click MB2.’) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN 


BUTTON_IS DOWN = 1 
CALL START SCROLL(DPY, WINDOW, GC, SCROLL_PIXELS, 


1 WINDOW W, WINDOW_H, VY) 
END IF 
IF (EVENT.EVNT_ TYPE .EQ. X$C_BUTTON PRESS .AND. 

1 EVENT.EVNT BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON2) THEN 

CALL SYSSEXIT ($VAL (1) ) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_GRAPHICS EXPOSE) THEN 
i] X = EVENT.EVNT_ GRAPHICS EXPOSE.X$L_GEEV_X 


Y = EVENT.EVNT GRAPHICS EXPOSE.X$L_GEEV_Y 
WIDTH = EVENT.EVNT_GRAPHICS EXPOSE.X$L_GEEV_WIDTH 
HEIGHT = EVENT.EVNT GRAPHICS EXPOSE.X$L_GEEV_HEIGHT 
DO PY = Y, Y + HEIGHT-1 
DO PX = X, X + WIDTH-1 
IF (MOD(PX + PY + VY, 10) .EQ. 0) THEN 
CALL X$DRAW POINT (DPY, WINDOW, GC, PX, PY) 
END IF 
END DO 
END DO 
IF (BUTTON IS DOWN .NE. 0) THEN 
CALL START SCROLL(DPY, WINDOW, GC, SCROLL PIXELS, 
1 WINDOW W, WINDOW_H, VY) 
END IF 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_RELEASE) THEN 
BUTTON IS DOWN = 0 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_NO EXPOSE) THEN 
IF (BUTTON IS DOWN .NE. 0) THEN 
CALL START _SCROLL(DPY, WINDOW, GC, SCROLL PIXELS, 
1 WINDOW W, WINDOW_H, VY) 
END IF 
END IF 
END DO 


START SCROLL SUBPROGRAM 


@°reoa 


SUBROUTINE START _SCROLL(DISP, WIN, GCONTEXT, SCR_PIX, WIN_W, 
z WIN_H, VEC_Y) 


INTEGER*4 DISP, WIN, GCONTEXT, SCR_PIX 
INTEGER*4 WIN_W, WIN_H, VEC_Y 
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Example 9-5 (Cont.) Handling Graphics Exposures 





9 CALL X$COPY_AREA(DISP, WIN, WIN, GCONTEXT, 0, 
1 SCR_PIX, WIN_W, WIN_H, 0, 0) 
VEC_Y = SCR_PIX + VEC_Y 


END 





@ When a graphics exposure occurs, the client calculates where to draw 
points into the exposed area by referring to members of the expose 
event data structure. 


@ The user-defined START_SCROLL routine copies the window contents, 
less one row of pixels, to the top of the window. The result leaves an 
exposed area one pixel high at the bottom of the window. 


© The COPY AREA routine copies new points into the exposed area. 
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Figure 9—13 Window Scrolling 





Graphics Exposure 


To scroll, press MB1. 
To exit, click MB2. 


ZK-0152A-GE 
9.9 Window State Notification Events 
Xlib reports events related to the state of a window when a client does one 
of the following: 
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Circulates a window, changing the order of the window hierarchy 
Configures a window, changing its position, size, or border 
Creates a window 

Destroys a window 

Changes the size of a parent, causing Xlib to move a child window 


Maps a window 


9.9.1 


Handling Events 
9.9 Window State Notification Events 


e Reparents a window 
¢ Unmaps a window 
¢ Changes the visibility of a window 


This section describes handling events that result from these operations. 


Handling Window Circulation 


To receive notification when a client circulates a window, pass either the 
window identifier and the x$m_structure_notify mask or the identifier of 
the parent window and the x$m_substructure_notify mask when using 
a selection method described in Section 9.2. 


Xlib reports to interested clients a change in the hierarchical position 

of a window when a client calls the CIRCULATE SUBWINDOWS, 
CIRCULATE SUBWINDOWS UP, or CIRCULATE SUBWINDOWS DOWN 
routines. 

Xlib uses the circulate event data structure to report circulate events. 
Figure 9-14 illustrates the data structure. . 


Figure 9-14 Circulate Event Data Structure 
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x$l_ciev_place — 


Table 9-19 describes members of the data structure. 





Table 9-19 Circulate Event Data Structure Members 


Member Name Contents 

X$L_CIEV_TYPE Value defined by the constant x$c_circulate_notify. 

X$L_CIEV_SERIAL Number of the last request processed by the 
server. 


(continued on next page) 
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Table 9-19 (Cont.) Circulate Event Data Structure Members 


Member Name 


X$L_CIEV_SEND_EVENT 


X$A_CIEV_DISPLAY 
X$L_CIEV_EVENT 
X$L_CIEV_WINDOW 
X$L_CIEV_PLACE 


Contents 


Value defined by the constant true if the event 
came from a SEND EVENT request. 


Display on which the event occurred. 


Event window. 
Window that has been circulated. 


~ Place of the window on the stack after it has been 


circulated. Xlib sets the value of this member 

to either the constant x$c_place_on_top or the 
constant x$c_place_on_bottom. The constant x$c_ 
place_on_top indicates that the window is above 
all siblings. The constant x$c_place_on_bottom 
indicates that the window is below all siblings. 


9.9.2 Handling Changes in Window Configuration 


To receive notification when window size, position, border, or stacking 
order changes, pass either the window identifier and the x$m_structure_ 
notify mask or the identifier of the parent window and the x$m_ 
substructure_notify mask when using the selection method described in 
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Section 9.2. 


Xlib reports changes in window configuration when the following occur: 


¢ Window size, position, border, and stacking order change when a client 
calls the CONFIGURE WINDOW routine 


¢ Window position in the stacking order changes when a client calls the 
~ LOWER WINDOW, RAISE WINDOW, or RESTACK WINDOW routine 


¢ Window moves when a client calls the MOVE WINDOW routine 
e¢ Window size changes when a client calls the RESIZE WINDOW 


routine 


¢ Window size and location change when a client calls the MOVE 


RESIZE WINDOW routine 


¢ Border width changes when a client calls the SET WINDOW BORDER 


WIDTH routine 


For more information about these routines, see Chapter 3. 


Xlib reports changes to interested clients using the configure event data 
structure. Figure 9-15 illustrates the data structure. 
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Figure 9-15 Configure Event Data Structure 
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Table 9-20 describes members of the data structure. 


Table 9-20 Configure Event Data Structure Members 


Member Name Contents 

X$L_CFEV_TYPE Value defined by the constant x$c_cfev_configure_notify. 

X$L_CFEV_SERIAL Number of the last request processed by the server. 

X$L_CFEV_SEND_EVENT Value defined by the constant true if the event came from a SEND 
EVENT request. 

X$A_CFEV_DISPLAY Display on which the event occurred. 

X$L_CFEV_EVENT Event window. 

X$L_CFEV_WINDOW Window that has been reconfigured. 

X$L_CFEV_X The x value of the coordinates that define the upper left corner of the 
window relative to the upper left corner of the parent window. 


X$L_CFEV_Y The y value of the coordinates that define the upper left corner of the 
window relative to the upper left corner of the parent window. 





(continued on next page) 
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Table 9-20 (Cont.) Configure Event Data Structure Members 


Member Name Contents 

X$L_CFEV_WIDTH Width of the window, excluding the border. 

X$L_CFEV_HEIGHT Height of the window, excluding the border. 
X$L_CFEV_BORDER_WIDTH Border width of the reconfigured window. 

X$L_CFEV_ABOVE Identifier of the sibling window above which the window is stacked. If this 


member has a value specified by the constant x$c_none, Xlib places the 
window at the bottom of the stack. 


X$L_CFEV_OVERRIDE. REDIRECT If this member has a value defined by the constant true, the window 
manager ignores requests to reconfigure the window. 





Handling Window Creations 


To receive notification when a client creates a window, pass the identifier 
of the parent window and the x$m_substructure_notify mask when 
using the selection method described in Section 9.2. 


Xlib reports window creations using the create window event data 
structure. Figure 9-16 illustrates the data structure. 


Figure 9-16 Create Window Event Data Structure 
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Table 9-21 describes members of the data structure. 


Table 9-21 Create Window Event Data Structure Members 


Member Name Contents 

X$L_CWEV_TYPE Value defined by the constant x$c_create_notify. 

X$L_CWEV_SERIAL Number of the last request processed by the server. 

X$L_CWEV_SEND_EVENT Value defined by the constant true if the event came from a SEND 
EVENT request. 

X$A_CWEV_DISPLAY Display on which the event occurred. 

X$L_CWEV_EVENT Parent window. 

X$L_CWEV_WINDOW Window that has been created. 

X$L_CWEV_X The x value of the coordinates that define the origin of the window. 

X$L_CWEV_Y The y value of the coordinates that define the origin of the window. 

X$L_CWEV_WIDTH Width of the newly created window, excluding the border. 

X$L_CWEV_HEIGHT Height of the newly created window, excluding the border. 

X$L_CWEV_BORDER_WIDTH Border width of the new window. 


X$L_CWEV_OVERRIDE_REDIRECT If this member has a value defined by the constant true, the window 
manager ignores requests to create the window. 





Handling Window Destructions 


To receive notification when a client destroys a window, pass either the 
window identifier and the x$m_structure_notify mask or the identifier of 
the parent window and the x$m_substructure_notify mask when using 
the selection method described in Section 9.2. 


Xlib reports window destructions using the destroy window event data 
structure. Figure 9-17 illustrates the data structure. 


Figure 9-17 Destroy Window Event Data Structure 
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Table 9~22 describes members of the data structure. 


Table 9-22 Destroy Window Event Data Structure Members 


Member Name Contents 

X$L_DWEV_TYPE Value defined by the x$c_destroy_notify constant. 

X$L_DWEV_SERIAL Number of the last request processed by the 

server. 

X$L_DWEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_DWEV_DISPLAY Display on which the event occurred. 

X$L_DWEV_EVENT Event window. 

X$L_DWEV_WINDOW Window that has been destroyed. 


Handling Changes in Window Position 


To receive notification when a window is moved because a client has 
changed the size of its parent, pass the window identifier and the x$m_ 
structure_notify mask or the identifier of the parent window and 

the x$m_substructure_notify mask when using the selection method 
described in Section 9.2. 


Xlib reports window gravity events using the gravity event data structure. 
Figure 9-18 illustrates the data structure. 


Figure 9-18 Gravity Event Data Structure 
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Table 9-23 describes members of the data structure. 


Table 9-23 Gravity Event Data Structure Members 








Member Name Contents 

X$L_GVEV_TYPE Value defined by the x$c_gravity_notify constant. 

X$L_GVEV_SERIAL Number of the last request processed by the 
server. 

X$L_GVEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_GVEV_DISPLAY Display on which the event occurred. 

X$L_GVEV_EVENT Event window. 

X$L_GVEV_WINDOW Child window that has moved. 

X$L_GVEV_X The x value of the coordinates that define the 


upper left corner of the window relative to the 
upper left corner of the parent window. 


X$L_GVEV_Y The y value of the coordinates that define the 
upper left corner of the window relative to the 
upper left corner of the parent window. 





Handling Window Mappings 


To receive notification when a window changes state from unmapped to 
mapped, pass either the window identifier and the x$m_structure_notify 
mask or the identifier of the parent window and the x$m_substructure_ 
notify mask when using the selection method described in Section 9.2. 


Xlib reports window gravity events using the map event data structure. 
Figure 9-19 illustrates the data structure. 


Figure 9-19 Map Window Event Data Structure 
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Table 9-24 describes members of the data structure. 


Table 9-24 Map Event Data Structure Members 


Member Name Contents 

X$L_MPEV_TYPE Value defined by the x$c_map_notify 
constant. 

X$L_MPEV_SERIAL Number of the last request processed by 
the server. 

X$L_MPEV_SEND_EVENT Value defined by the constant true if 
the event came from a SEND EVENT 
request. 

X$A_MPEV_DISPLAY Display on which the event occurred. 

X$L_MPEV_EVENT Event window. 

X$L_MPEV_WINDOW Window that has been mapped. 

X$L_MPEV_OVERRIDE_REDIRECT If the value of this member is defined by 


the constant true, the window manager 
should disregard requests to map the 
window. When true, it overrides a 
substructure redirect on the parent. 


Handling Key, Keyboard, and Pointer Mappings 


All clients receive notification of changes in key, keyboard, and pointer 
mapping. Xlib reports these events when a client has successfully done 
one of the following: 


¢ Called the SET MODIFIER MAPPING routine to indicate which 
keycodes are modifiers 


e Changed keyboard mapping using the CHANGE KEYBOARD 
MAPPING routine 


e Set pointer mapping using the SET POINTER MAPPING routine 


Xlib reports key, keyboard, and pointer mapping events using the mapping 
event data structure. Figure 9-20 illustrates the data structure. 


Figure 9-20 Mapping Event Data Structure 
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Figure 9-20 (Cont.) Mapping Event Data Structure 






x$l_mppg_request 20 
x$l_mppg_first_keycode 24 
x$l_mppg_count 28 
Table 9-25 describes members of the data structure. 
Table 9-25 Mapping Event Data Structure Members 
Member Name Contents 
X$L_MPPG_TYPE Value defined by the x$c_mapping_notify constant. 
X$L_MPPG_SERIAL Number of the last request processed by the server. 
X$L_MPPG_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 
X$A_MPPG_DISPLAY Display on which the event occurred. 
X$L_MPPG_WINDOW Unused member. 
X$L_MPPG_REQUEST The type of mapping change being reported. Possible values are indicated 
by the following constants: 
x$c_mapping_modifier Specified key codes are used as 
. modifiers. 
x$c_mapping_keyboard Keyboard mapping has changed. Sets 
the X$L_MPPG_FIRST_KEYCODE and 
X$L_MPPG_COUNT members. 
x$c_mapping_pointer Pointer button mapping is set. 
X$L_MPPG_FIRST_KEYCODE First number of the range of altered keys, set only if the request member 
has a value specified by the constant x$c_mapping_keyboard. 
X$L_MPPG_COUNT Last number of the range of altered keys, set only if the request member 


has a value specified by the constant x$c_mapping_keyboard. 





Handling Window Reparenting 


To receive notification when the parent of a window changes, pass 
either the window identifier and the x$m_structure_notify mask or 
the identifier of the parent window and the x$m_substructure_notify 
mask when using the selection method described in Section 9.2. 


Xlib reports window reparenting events using the reparent event data 
structure. Figure 9-21 illustrates the data structure. 
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Figure 9-21 Reparent Event Data Structure 


















x$l_rpev_type | 0 
x$l_rpev_serial 4 
x$|_rpev_send_event 8 
x$a_rpev_display 12 
x$l_rpev_event 16 
x$l_rpev_window 20 
x$l_rpev_parent 24 
x$l_rpev_x 28 
x$l_rpev_y 32 
x$l_rpev_override_redirect 36 
Table 9-26 describes members of the data structure. 
Table 9-26 Reparent Event Data Structure Members 
Member Name Contents 
X$L_RPEV_TYPE Value defined by the x$c_reparent_notify constant. 
X$L_RPEV_SERIAL Number of the last request processed by the server. 
X$L_RPEV_SEND_EVENT Value defined by the constant true if the event came from a SEND 
EVENT request. : 
X$A_RPEV_DISPLAY Display on which the event occurred. 
X$L_RPEV_EVENT Event window. 
X$L_RPEV_WINDOW Window reparented. 
X$L_RPEV_PARENT New parent of the window. 
X$L_RPEV_X The x value of the coordinates that define the upper left corner of the 
window relative to the upper left corner of the parent window. 
X$L_RPEV_Y The y value of the coordinates that define the upper left corner of the 
window relative to the upper left corner of the parent window. 
X$L_RPEV_OVERRIDE_REDIRECT If this member has a value defined by the constant true, the window 


manager ignores requests to reparent the window. When true, it 
overrides a substructure redirect on the parent. 
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Handling Window Unmappings 


To receive notification when a window changes from mapped to unmapped, 
pass either the window identifier and the x$m_structure_notify mask 
or the identifier of the parent window and the x$m_substructure_notify 
mask when using the selection method described in Section 9.2. 


Xlib reports window unmapping events using the unmap event data 
structure. Figure 9-22 illustrates the data structure. 


Figure 9-22 Unmap Event Data Structure 
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Table 9-27 describes members of the data structure. 
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Table 9-27 Unmap Event Data Structure Members 


Member Name Contents 


X$L_UMEV_TYPE Value defined by the x$c_unmap_notify 
constant. 


X$L_UMEV_SERIAL Number of the last request processed by the 
server. 
X$L_UMEV_SEND_EVENT Value defined by the constant true if the 
event came from a SEND EVENT request. 
X$A_UMEV_DISPLAY Display on which the event occurred. 
X$L_UMEV_EVENT Event window. 
X$L_UMEV_WINDOW Window unmapped. 
X$L_UMEV_FROM_CONFIGURE If the value of this member is defined by 
the constant true, the event occurred as a 
result of resizing the parent window when the 


window itself has a window gravity specified 
by the constant x$c_unmap_gravity. 
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Handling Changes in Window Visibility 


All or part of a window is visible if it is mapped to a screen, if all of its 
ancestors are mapped, and if it is at least partially visible on the screen. 
To receive notification when the visibility of a window changes, pass the 
window identifier and the x$m_structure_notify mask when using the 
selection method described in Section 9.2. 


Xlib reports changes in visibility to interested clients using the visibility 
event data structure. Figure 9-23 illustrates the data structure. 


Figure 9-23 Visibility Event Data Structure 
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Table 9-28 describes members of the data structure. 


Table 9~-28 Visibility Event Data Structure Members 








Member Name Contents 

X$L_VSEV_TYPE Value defined by the x$c_visibility_notify constant. 

X$L_VSEV_SERIAL Number of the last request processed by the server. 

X$L_VSEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
_ request. 

X$A_VSEV_DISPLAY Display on which the event occurred. 

X$L_VSEV_WINDOW Window whose visibility changed. 

X$L_VSEV_STATE if set to the value defined by the x$c_visibility_unobscured constant, the 


window has changed from being partially and fully obscured to being fully 
visible. If set to the value defined by the x$c_visibility_part_obscured, the 
window has changed from being fully obscured or fully visible to partially 
obscured. If set to the value defined by the x$c_visibility_fully_obscured 
constant, the window has changed from being fully visible or partially obscured 
to not visible. 
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Color Map State Events 


Xlib reports a color map event when the window manager installs, 
changes, or removes the color map. 


To receive notification of color map events, pass the window identifier 
and the x$m_colormap_change mask when using the selection method 
described in Section 9.2. 


Xlib reports color map events to interested clients when the following 
occur: 


¢ Aclient sets the color map member of the set window attributes data 
structure by calling CHANGE WINDOW ATTRIBUTES. See Chapter 3 
for more information on the data structure and routine. 


¢ Aclient calls the FREE COLORMAP routine. See Section 5.5 for more 
information about FREE COLORMAP. 


¢ The window manager installs or removes a color map in response 
to either a client call of the INSTALL COLORMAP or UNINSTALL 
COLORMAP routine. 


Xlib reports color map events using the color map event data structure. 
Figure 9-24 illustrates the data structure. 


Figure 9-24 Color Map Event Data Structure 
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Table 9~29 describes members of the data structure. 


Table 9-29 Color Map Event Data Structure Members 


Member Name 


Contents 





X$L_CMEV_TYPE 
X$L_CMEV_SERIAL 
X$L_CMEV_SEND_EVENT 


X$A_CMEV_DISPLAY 


X$L_CMEV_WINDOW 


X$L_CMEV_COLORMAP 


X$L_CMEV_NEW 


X$L_CMEV_STATE 


Value defined by the x$c_colormap_notify constant. 
Number of the last request processed by the server. 


Value defined by the constant true if the event came from a SEND EVENT 
request. 


Display on which the event occurred. 
Window whose associated color map has changed. 


If the window manager changes the color map in response to a call to CHANGE 
WINDOW ATTRIBUTES, INSTALL COLORMAP, or UNINSTALL COLORMAP, 
this member has a value specified by the constant x$c_colormap. If the window 
manager changes the color map in response to a call to FREE COLORMAP, 
this member has a value specified by the constant x$c_none. 


Value defined by the constant true if the window manager has changed the 
color map or the value defined by the constant false if the window manager has 
installed or removed the color map. 


Value defined by the constant x$c_colormap_installed if the color map is 


installed. The value defined by the constant x$c_colormap_uninstalled if the 


color map is not installed. 





9.11 Client Communication Events 


Xlib reports an event when one of the following occurs: 

One client notifies another client that an event has happened. 
A client changes, deletes, rotates, or gets a property. 

A client loses ownership of a window. 


A client requests ownership of a window. 


This section describes how to handle communication between clients. 


9.11.1 Handling Event Notification from Other Clients 


Clients can notify each other of events by calling the SEND EVENT 
routine. 


Xlib sends notification between clients using the client message event data 
structure. Figure 9-25 illustrates the data structure. 
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Figure 9-25 Client Message Event Data Structure 











x$l_cint_type 0 
x$l_cint_serial 4 
x$l_clnt_send_event 8 
x$a_clnt_display 12 
x$l_cint_window 16 
x$l_cint_message_type . 20 
x$l_cint_format 24 
x$b_clnt_b (20 bytes) 28 
Table 9-30 describes members of the data structure. 
Table 9-30 Client Message Event Data Structure Members 
Member Name Contents 
X$L_CLNT_TYPE Value defined by the x$c_client_message constant. 
X$L_CLNT_SERIAL Number of the last request processed by the server. 
X$L_CLNT_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 
X$A_CLNT_DISPLAY Display on which the event occurred. 
X$L_CLNT_WINDOW Window to which the message is sent. 
X$L_CLNT_MESSAGE_TYPE Indicates how the message data is to be interpreted by the receiving client. 
For more information about atoms, see Chapter 3. 
X$L_CLNT_FORMAT Indicates whether the data is in units of 8, 16, or 32 bits. 
X$B_CLNT_B Data of 20 8-bit values. | 


9.11.2 Handling Changes in Properties 


As Chapter 3 notes, a property associates a constant with data of a 
particular type. Xlib reports a property event when a client does one of 
the following: 


¢ Changes a property 
¢ Rotates a window property 


¢ Gets a property 
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e Deletes a property 


To receive information about property changes, pass the window identifier 
and the x$m_property_change mask when using the selection method 
described in Section 9.2. 


Xlib reports changes in properties to interested clients using the property 
event data structure. Figure 9-26 illustrates the data structure. 


Figure 9-26 Property Event Data Structure 














x$l_ppev_type 0 
x$l_ppev_serial 4 
x$l_ppev_send_event 8 
x$a_ppev_display 12 
x$l_ppev_window 16 
x$l_ppev_atom 20 
x$l_ppev_time 24 
x$l_ppev_state 28 
Table 9-31 describes members of the data structure. 
Table 9-31 Property Event Data Structure Members 
Member Name — Contents 
X$L_PPEV_TYPE Value defined by the x$c_property_notify constant. 
X$L_PPEV_SERIAL Number of the last request processed by the server. 
X$L_PPEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 
X$A_PPEV_DISPLAY Display on which the event occurred. 
X$L_PPEV_WINDOW Window whose property was changed. 
X$L_PPEV_ATOM Identifies the property that was changed. For more information about properties 


and atoms, see Chapter 3. 
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Table 9-31 (Cont.) Property Event Data Structure Members 





Member Name Contents 
X$L_PPEV_TIME Server time that the property changed. 
X$L_PPEV_STATE Value specified by the constant x$c_property_new_value if a client changes 


a property by calling either the CHANGE PROPERTY or the ROTATE 
PROPERTY routine. The same result occurs if the client replaces all or 

part of a property with identical data using © CHANGE PROPERTY or ROTATE 
PROPERTY. . 

The value specified by the constant x$c_property_delete if a client deletes a 
property by calling either the DELETE PROPERTY or the GET PROPERTY 
routine. For more information about properties, see Chapter 3. 


Handling Changes in Selection Ownership 


Clients receive notification automatically when they are losing ownership 
of a window. Xlib reports the event when a client takes ownership of a 
window by calling the SET SELECTION OWNER routine. 


To report the event, Xlib uses the selection clear event data structure. 
Figure 9-27 illustrates the data structure. 


Figure 9-27 Selection Clear Event Data Structure 
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Table 9-32 describes menibers of the data structure. 

Table 9-32 Selection Clear Event Data Structure Members 

Member Name Contents 

X$L_SCEV_TYPE Value defined by the x$c_selection_clear constant. 
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Table 9-32 (Cont.) Selection Clear Event Data Structure Members 





Member Name Contents 

X$L_SCEV_SERIAL Number of the last request processed by the 
server. 

X$L_SCEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_SCEV_DISPLAY Display on which the event occurred. 

X$L_SCEV_WINDOW Window losing ownership of the selection. 

X$L_SCEV_SELECTION _ Selection atom. For more information about atoms 
and selection, see Chapter 3. 

X$L_SCEV_TIME . Last time change recorded for the selection. 





9.11.4 Handling Requests to Convert a Selection 


The server issues a selection request event to the owner of a selection 
when a client calls the CONVERT SELECTION routine. For information 
about the CONVERT SELECTION routine, see Section 3.5.2. 


To report the event, Xlib uses the selection request event data structure. 
Figure 9-28 illustrates the data structure. 


Figure 9-28 Selection Request Event Data Structure 





Table 9-33 describes members of the selection request event data 
structure. 
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Table 9-33 Selection Request Event Data Structure Members 


Member Name Contents 
_ X$L_SREV_TYPE Value defined by the x$c_selection_request 
. constant. 

X$L_SREV_SERIAL Number of the last request processed by the 
server. 

X$L_SREV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_SREV_DISPLAY Display on which the event occurred. 

X$L_SREV_OWNER Window that owns the selection. 

X$L_SREV_REQUESTOR Window that requests the selection. 

X$L_SREV_SELECTION Selection atom. For more information about atoms 
and selection, see Chapter 3. 

X$L_SREV_TARGET Data type that selection is converted to before 
being returned. 

X$L_SREV_PROPERTY Atom that specifies a property or the constant 
x$c_none. 

X$L_SREV_TIME Timestamp, expressed in milliseconds, or the 


constant x$c_current_time from the convert 
selection request. 


9.11.5 Handling Requests to Notify of a Selection 


The server issues a selection notify event to the requestor of a selection 
after the selection has been converted and stored as a property. 


For information about the CONVERT SELECTION routine, see 
Section 3.5.2. To report the event, Xlib uses the selection event data 
structure. Figure 9-29 illustrates the data structure. 


Figure 9-29 Selection Event Data Structure 
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Figure 9-29 (Cont.) Selection Event Data Structure 













x$l_slev_property 28 
x$l_slev_time 32 
Table 9-34 describes members of the selection event data structure. 
Table 9-34 Selection Event Data Structure Members 
Member Name | Contents 
X$L_SLEV_TYPE Value defined by the x$c_selection_notify constant. 
X$L_SLEV_SERIAL Number of the last request processed by the 
server. 
X$L_SLEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 
X$A_SLEV_DISPLAY Display on which the event occurred. 
X$L_SLEV_REQUESTOR Window that has requested the selection. 
X$L_SLEV_SELECTION Selection atom. For more information about atoms 
and selection, see Chapter 3. 
X$L_SLEV_TARGET Data type to which selection is converted. 
X$L_SLEV_PROPERTY Atom that specifies a property or the constant 
x$c_none. 
X$L_SLEV_TIME Timestamp, expressed in milliseconds, or the 


constant x$c_current_time from the convert 
selection request. 





9.12 Event Queue Management 


Xlib maintains an input queue known as the event queue. When an 
event occurs, the server sends the event to Xlib, which places it at the end 
of an event queue. By using routines described in this section, the client 
can check, remove, and process the events on the queue. As the client 
removes an event, remaining events move up the event queue. 


Certain routines may block or prevent other routine calls from accessing 
the event queue. If the blocking routine does not find an event that the 
client is interested in, Xlib flushes the output buffer and waits until an 
event is received from the server. 


This section describes how the event queue is managed, including the 
following topics: 


e Checking events on the queue 
e Returning events in order and removing them from the queue 


e Returning events without removing them from the queue 
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¢ Obtaining events that match the event mask or the arbitrary functions 
that the client provides 


e Putting events back onto the event queue 


e Sending events to other clients 


9.12.1 Checking the Contents of the Event Queue 


To check the event queue without preventing other routines from accessing 
the queue, use the EVENTS QUEUED routine. Clients can check events 
already queued by calling the EVENTS QUEUED routine and specifying 
one of the following constants: 


x$c_queued_already Returns the number of events already in the event 
queue and never performs a system call. 
x$c_queued_after_flush Returns the number of events in the event queue if 


the value is a nonzero. If there are no events in the 
queue, this routine flushes the output buffer, attempts 
to read more events out of the client connection, and 
returns the number read. 

x$c_queued_after_reading Returns the number of events already in the event 
queue if the value is a nonzero. If there are no events 
in the queue, this routine attempts to read more 
events out of the client connection without flushing the 
output buffer and returns the number read. 


To return the number of events in the event queue, use the PENDING 
routine. If there are no events in the queue, PENDING flushes the output 
buffer, attempts to read more events out of the client connection, and 
returns the number read. The PENDING routine is identical to EVENTS 
QUEUED with constant x$c_queued_after_flush specified. 


9.12.2 Returning the Next Event on the Queue 


To return the first event on the event queue and copy it into the specified 
event data structure, use the NEXT EVENT and PEEK EVENT routines. 
NEXT EVENT returns the first event, copies it into an EVENT structure, 
and removes it from the queue. PEEK EVENT returns the first event, 
copies it into an event data structure, but does not remove it from the 
queue. In both cases, if the event queue is empty, the routine flushes the 
output buffer and blocks until an event is received. 


9.12.3 Selecting Events That Match User-Defined Routines 


Xlib enables the client to check all the events on the queue for a specific 
type of event by specifying a client-defined routine known as a predicate 
procedure. The predicate procedure determines if the event on the queue 
is one that the client is interested in. 


The client calls the predicate procedure from inside the event routine. 
The predicate procedure should determine only if the event is useful and 
must not call Xlib routines. The predicate procedure is called once for each 
event in the queue until it finds a match. 
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Table 9-35 lists routines that use a predicate procedure and indicates 
whether or not the routine blocks. 


Table 9-35 Selecting Events Using a Predicate Procedure 
Routine Description Blocking/No Blocking 





IF EVENT Checks the event queue for the specified event. Blocking 
If the event matches, removes the event from the 
queue. This routine is also called each time an 
event is added to the queue. 

CHECK IF EVENT Checks the event queue for the specified event. No blocking 
lf the event matches, removes the event from the 
queue. lf the predicate procedure does not find a 
match, it flushes the output buffer. 

PEEK IF EVENT Checks the event queue for the specified event but Blocking 
does not remove it from the queue. This routine 
is also called each time an event is added to the 
queue. 


Selecting Events Using an Event Mask 


Xlib enables a client to process events out of order by specifying a window 
identifier and one of the event masks listed in Table 9-3 when calling 
routines listed in Table 9-36. 


For example, the following specifies keyboard events on window WINDOW 
by using the event mask name constant x$c_keymap_state_mask. 


CALL X$WINDOW_EVENT (DPY, WINDOW, 
1 X$C_KEYMAP_ STATE, EVENT) 


Table 9-36 lists routines that use event or window masks and indicates 
whether the routine blocks. 


Table 9-36 Routines to Select Events Using a Mask 


Routine Description | Blocking/No Blocking 
WINDOW EVENT Searches the event queue and removes the next Blocking 

event that matches both the specified window and 

event mask 
CHECK WINDOW EVENT __ Searches the event queue, then the events No blocking 


available on the server connection, and removes 
the first event that matches the specified event and 
window mask 


MASK EVENT Searches the event queue and removes the next Blocking 
event that matches the event mask 
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Table 9-36 (Cont.) Routines to Select Events Using a Mask 


Routine 


CHECK MASK EVENT 


CHECK TYPED EVENT 


CHECK TYPED WINDOW 
EVENT 


Description Blocking/No Blocking 


Searches the event queue, then the events No blocking 
available on the server connection, and removes 
the next event that matches an event mask 


Returns the next event in the queue that matches No blocking 
an event type 


Searches the event queue, then the events No blocking 
available on the server connection, and removes 

the next event that matches the specified type and 

window 


Putting an Event Back on Top of the Queue 


To push an event back onto the top of the event queue, use the PUT BACK 
EVENT routine. PUT BACK EVENT is useful when a client returns an 
event from the queue and decides to use it later. There is no limit to how 
many times in succession PUT BACK EVENT can be called. 


Sending Events to Other Clients 


To send an event to a client, use the SEND EVENT routine. For example, 
owners of a selection should use this routine to send a SELECTION 
NOTIFY event to a requestor when a selection has been converted and 
stored as a property. 





Error Handling 


Xlib has two default error handlers. One manages fatal errors, such as 
when the connection to a display is severed due to a system failure. The 
other handles error events from the server. The default error handlers 
print an explanatory message and text and then exit. 


Each of these error handlers can be replaced by client error handling 
routines. If a client-supplied routine is passed a null pointer, Xlib 
reinvokes the default error handler. 


‘This section describes the Xlib event error handling resources including 


enabling synchronous operation, handling server errors, and handling 
input/output (I/O) errors. 


Enabling Synchronous Operation 


When debugging programs it is convenient to require Xlib to behave 
synchronously so that errors are reported at the time they occur. 


To enable synchronous operation, use the SYNCHRONIZE routine. The 
client passes the display argument and the onoff argument. The onoff 
argument passes either a value of zero (disabling synchronization) or a 
nonzero value (enabling synchronization). 
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9.13.2 Using the Default Error Handlers 


To handle error events when an error event is received, use the SET 
ERROR HANDLER routine. 


Xlib provides an error event data structure that passes information to the 
SET ERROR HANDLER routine. 


Figure 9-30 illustrates the error event data structure. 


Figure 9-30 Error Event Data Structure 
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x$b_erev_minor_code x$b_erev_request_code x$b_erev_error_code 


Table 9-37 describes the members of the data structure. 





Table 9-37 Error Event Data Structure Members 


Member Name ‘Description 

X$L_EREV_TYPE Type of error event being reported 

X$A_EREV_DISPLAY Display on which the error event occurred 

X$L_EREV_SERIAL Number of requests starting at one sent over the 
network connection since it was opened 

X$B_EREV_ERROR_CODE Identifying error code of the failing routine 


X$B_EREV_REQUEST_CODE Protocol representation of the name of the 
procedure that failed and defined in X11/X.h 


X$B_EREV_MINOR_CODE Minor opcode of failed request 
X$L_EREV_RESOURCE_ID Resource ID 





The routines described in this section return Xlib error codes. Table 9-38 
lists the codes and describes the errors. 
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Table 9-38 Event Error Codes 


Error Code 


Description 





X$C_BAD_ACCESS 


X$C_BAD_ALLOC 
X$C_BAD_ATOM 
X$C_BAD_COLOR 
X$C_BAD_CURSOR > 
X$C_BAD_DRAWABLE 


X$C_BAD_FONT: 
X$C_BAD_GC 


X$C_BAD_ID_CHOICE 


X$C_BAD_ 
IMPLEMENTATION 


X$C_BAD_LENGTH 


X$C_BAD_MATCH 


X$C_BAD_NAME 
X$C_BAD_PIXMAP 


Possible causes are: 


¢ An attempt to grab a key/button combination that has already been grabbed by 
another client. 

¢ An attempt to free a color map entry that was not allocated by the client. 

¢ An attempt to store into a read-only, or unallocated, color map entry. 

¢ An attempt to modify the access control list from other than the local host. 

¢ An attempt to select an event type that only one client can select at a time when 
another client has already selected it. 

The server did not allocate the requested resource for any cause. 

The value specified in an atom argument does not name a defined atom. 

A value specified for a color map argument does not name a defined color map. 

A value specified for a cursor argument does not name a defined cursor. 

A value specified for a drawable argument does not name a defined window or 

pixmap. 

A value specified for a font argument does not name a defined font (or, in some 


‘cases, graphics context). 


A value specified for a graphics context argument does not name a defined graphics 
context. 


The value specified for a resource identifier is either not included in the range 
assigned to the client, or is already in use. Under normal circumstances this cannot 
occur and should be considered a server or Xlib error. 


The server does not implement some aspect of the request. This error is most likely 
caused by a server extension; a server that generates this error for a core protocol 
request is deficient. As such, this error is not listed for any particular request. Clients 
should be prepared to receive this type of error and either handle or discard it. 


The length of a request is shorter or longer than required to minimally contain the 
arguments. This error usually indicates an internal Xlib or server error. The length of 
a request exceeds the maximum length accepted by the server. 


Possible causes are: 

¢ Ina graphics request, the root and depth of the graphics context does not match 
that of the drawable. 

¢ An input-only window is used as a drawable. 


¢ One argument or pair of arguments has the correct type and range but fails to 
match in some other way required by the request. 


¢ — An input only window lacks this attribute. 


The font or color specified does not exist. 
A value specified for a pixmap argument does not name a defined pixmap. 
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Table 9-38 (Cont.) Event Error Codes 


Error Code 
X$C_BAD_REQUEST 


X$C_BAD_VALUE 


X$C_BAD_WINDOW 


Description 


The major or minor opcode specified does not indicate a valid request. This is usually 
an Xlib or. server error. 


Some numeric values fall outside the range of values accepted by the request. 
Unless a specific range is specified for an argument, the full range defined by the 
argument’s type is accepted. Any argument defined as a set of alternatives can 
generate this error. 


A value specified for a window argument does not name a defined window. 


Note that Bad Atom, Bad Color, Bad Cursor, Bad Drawable, Bad Font, 
Bad Pixmap, and Bad Window errors are also used when the argument 
type is extended by a set of fixed alternatives. 


To obtain a text description of the specified error code, use the GET 
ERROR TEXT routine. This routine copies a null terminated string 
describing the specified error code into the specified buffer. The client 
should use this routine to obtain an error description because extensions 
to Xlib may define their own error codes and error strings. 


To obtain error messages from the error database, use the GET ERROR 
DATABASE TEXT routine. This routine returns a message (or the default 
message) from the error message database. The GET ERROR DATABASE 
TEXT uses the resource manager to look up a string and returns it in the 
buffer argument. Xlib uses this function internally to look up its error 
messages. 


To report an error when the requested display does not exist, use the 
DISPLAY NAME routine. This routine returns the name of the display 
that the client is currently using. The DISPLAY NAME routine passes 
the argument string. If null string is specified, DISPLAY NAME looks in 
the environment and returns the display name requested. This makes it 
easier to report precisely which display the client attempted to open when 
the initial connection attempt failed. 


To handle fatal I/O errors, use the SET IO ERROR HANDLER routine. 
Xlib calls the supplied error handler if any system call error occurs (for 
example, the connection to the server is lost). In this case, the called 
routine should not return. If the I/O handler does return, the client exits. 


9.13.3 Confirming X Resource Creation 


When creating any X resource, such as a window, pixmap, or ge, it is 
important to note that these routines are asynchronous and do not return 
errors if the create fails. Although Xlib returns a resource id for these 
routines, it does not indicate that a valid resource was created by the 
server. 


Use the following method to check if the client has successfully created a 
resource: 


1 Provide a client-defined error handler and specify it by calling the SET 
ERROR HANDLER routine. 
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Call the NEXT REQUEST routine. The NEXT REQUEST routine 
returns the serial number that Xlib is to use for the next request. 


Call the routine to create the resource, such as CREATE PIXMAP. 


Call the SYNC routine. The SYNC routine forces all requests in the 
output buffer to be processed by the server and returns any errors to 
the error handler. 


Use the error handler to compare the x$l_erev_serial member of the 
error event data structure with the serial number returned by the 
NEXT REQUEST routine. The value of the x$l_erev_serial member 
in the error event data structure reflects the number of the request 
immediately before the failing call was made. Therefore, if the values 
are equal, the create has failed. 
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Compiling Fonts 


VMS DECwindows includes a font compiler that enables programmers 
to convert an ASCII bitmap distribution format (BDF) into binary server 
natural form (SNF). The server uses an SNF file to display a font. In 
addition to converting the BDF file to binary form, the compiler provides 
statistical information about the font and the compilation process. 


To invoke the font compiler, use the following format: 


FONT filespec [ 
/[NOJOUTPUT[=filename] 
/[NO]JMINBBOX 
/[NOJREPORT 


] 


The filename parameter specifies the BDF file to be converted. A 
file name is required. The default value of the optional file type is 
DECWS$BDE. 


The /OUTPUT qualifier specifies the file name and type of the resulting 
SNF file. The default output file name is the file name of the BDF file 
being converted. The default output SNF file type is DECW$FONT. 


Compiler output consists of a header file that contains font information, 
character metrics, and the image of each character in the font. Font 
information in the header file is essentially the same as information stored 
in the font struct data structure. For a description of the data structure, 
see Section 8.1. 


The /MINBBOX qualifier specifies that the compiler produce the minimum 
bounding box for each character in the font and adjust values for the left 
bearing, right bearing, ascent, and descent of each character accordingly. 
Character width is not affected. Specifying the /MINBBOX qualifier 

is equivalent to converting a fixed font to a monospaced font. For a 
description of character metrics and fonts, see Section 8.1. 


Using the /MINBBOX qualifier has two advantages. Because the font 
compiler produces minimum instead of fixed bounding boxes, the resulting 
SNF file is significantly smaller than the comparable fixed font SNF file. 
Consequently, both disk requirements for storing the font and server 
memory requirements when a client loads the font are reduced. Also, 
because the resulting font comprises minimum inkable characters, server 
performance when writing text is increased as much as 20 percent. 


The /REPORT qualifier directs the compiler to report information about 
the font and the conversion process, including BDF information, font 
properties, compiler generation information, and metrics. The /REPORT 
qualifier also causes the compiler to illustrate each glyph in the font. 


Routines Requiring Protocol Requests 


Table B—1 lists Xlib routines requiring protocol requests. The table 
provides the protocol request and a short description for each Xlib function. 


Table B—1 Routines Requiring Protocol Requests 


Xlib Function 


ACTIVATE SCREEN SAVER 


ADD HOST 


ADD HOSTS 


ADD TO SAVE SET 
ALLOC COLOR 
ALLOC COLOR CELLS 


ALLOC COLOR PLANES 


ALLOC NAMED COLOR 


ALLOW EVENTS 


AUTO REPEAT OFF 


AUTO REPEAT ON 


BELL 


CHANGE ACTIVE POINTER GRAB 


CHANGE GC 


CHANGE KEYBOARD CONTROL 


CHANGE KEYBOARD MAPPING 


Protocol Request 


FORCE SCREEN SAVER 
CHANGE HOSTS 
CHANGE HOSTS 


CHANGE SAVE SET 
ALLOC COLOR 
ALLOC COLOR CELLS 


ALLOC COLOR PLANES 


ALLOC NAME COLOR 


ALLOW EVENTS 


CHANGE KEYBOARD 
CONTROL 


CHANGE KEYBOARD 
CONTROL 


BELL 


CHANGE ACTIVE POINTER 
GRAB 


CHANGE GC 


CHANGE KEYBOARD 
CONTROL 


CHANGE KEYBOARD 
MAPPING 


Description 
Enables the screen saver, even if it is 
currently disabled 


Adds a host to the list of hosts that can 
connect to a display 


Adds more than one host to the list of 
hosts that can connect to a display 


Adds a window to the client’s save set 
Allocates a read-only color cell 


Allocates read/write color cells and 
color plane combinations for a 
PseudoColor model 


Allocates read/write color resources for 
DirectColor visual types 


Allocates a read-only color cell by 
name and returns the closest color 
supported by the hardware 


Releases events that were queued 
because a device was grabbed 


Turns off keyboard auto-repeat 
Turns on keyboard auto-repeat 


Rings the keyboard bell at the base 
volume specified 

Changes the dynamic parameters for 
an active grab 

Changes the components in the 
specified graphics context 

Changes the keyboard setting for the 


key click volume, base bell volume, 
LEDs, and auto-repeat keys 


Specifies key symbols for the selected 
key codes 
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Xlib Function 


CHANGE POINTER CONTROL 
CHANGE PROPERTY 

CHANGE SAVE SET 

CHANGE WINDOW ATTRIBUTES 
CIRCULATE SUBWINDOWS 
CIRCULATE SUBWINDOWS DOWN 
CIRCULATE SUBWINDOWS UP 
CLEAR AREA 

CLEAR WINDOW 

CONFIGURE WINDOW 
CONVERT SELECTION 


COPY AREA 


COPY COLORMAP AND FREE 


COPY GC 


COPY PLANE 


CREATE COLORMAP 
CREATE FONT CURSOR 
CREATE GC 


CREATE GLYPH CURSOR 
CREATE PIXMAP 
CREATE PIXMAP CURSOR 


Protocol Request 


CHANGE POINTER CONTROL 
CHANGE PROPERTY 
CHANGE SAVE SET 
CHANGE WINDOW 
ATTRIBUTES 
CIRCULATE WINDOW 
CIRCULATE WINDOW 
CIRCULATE WINDOW 
CLEAR AREA 

CLEAR AREA 
CONFIGURE WINDOW 
CONVERT SELECTION 


COPY AREA 


COPY COLORMAP AND FREE 


COPY GC 


COPY PLANE 


CREATE COLORMAP 
CREATE GLYPH CURSOR 
CREATE GC 


CREATE GLYPH CURSOR 
CREATE PIXMAP 
CREATE CURSOR 


Description 


‘Controls the interactive feel of the 


pointing device 
Changes the property of a specified 
window 


Adds or removes a window from the 
client’s save set 


Changes one or more window 
attributes 


Circulates a subwindow up or down 


Lowers the highest mapped child of 
a window that partially or completely 
occludes another child 


Raises the lowest mapped child of an 
occluded window 


Clears a specified rectangular area of 
the specified window 


Clears the entire area in the specified 
window 


Configures a window’s size, location, 
stacking, or border 


Requests conversion of a selection 


Copies an area of the specified 
drawable between drawables of the 
same root and depth 


Creates a new color map when 
allocating out of a previously shared 
color map has failed due to resource 
exhaustion 


Copies components from a source 


graphics context to a destination 


graphics context 


Copies a single bit-plane of the 
specified drawable 


Creates a color map for a screen 
Creates a cursor from a standard font 


Creates a new graphics context that is 
usable with the specified drawable 


Creates a cursor from font glyphs 
Creates a pixmap of a specified size 
Creates a cursor from two bitmaps 





(continued on next page) 


Table B—1 (Cont.) Routines Requiring Protocol Requests 


Xlib Function 
CREATE SIMPLE WINDOW 


CREATE WINDOW 
DEFINE CURSOR 

DELETE PROPERTY 
DESTROY SUBWINDOWS 
DESTROY WINDOW 
DISABLE ACCESS CONTROL 
DRAW ARG 
DRAW ARCS 
DRAW IMAGE STRING 
DRAW IMAGE STRING 16 
DRAW LINE 
DRAW LINES 
DRAW POINT 
DRAW POINTS 
DRAW RECTANGLE 
DRAW RECTANGLES 


DRAW SEGMENTS 


DRAW STRING 


DRAW STRING 16 
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Protocol Request 


CREATE WINDOW 


CREATE WINDOW 
CHANGE WINDOW 
ATTRIBUTES 

DELETE PROPERTY 
DESTROY SUBWINDOWS 
DESTROY WINDOW 
SET ACCESS CONTROL 
POLY ARC 

POLY ARC 

IMAGE TEXT 8 

IMAGE TEXT 16 

POLY SEGMENT 

POLY LINE 

POLY POINT 

POLY POINT 

POLY RECTANGLE 


POLY RECTANGLE 


POLY SEGMENT 


POLY TEXT 8. 


POLY TEXT 16 


Description 


Creates an unmapped input-output 
subwindow of the specified parent 
window 


Creates an unmapped subwindow for a 
specified parent window 


Defines which cursor will be used in a 
window 


Deletes a property for the specified 
window 


Destroys all subwindows of a specified 
window 


Destroys a window and all of its 
subwindows 


Disables access control mode for a 
display 7 

Draws a single arc in the specified 
drawable 


Draws multiple arcs in the specified 
drawable 


Draws 8-bit image text characters in 
the specified drawable 


Draws 2-byte image text characters in 
the specified drawable 


Draws a single line between two points 
in the specified drawable 


Draws multiple lines in the specified 
drawable 


Draws a single point in the specified 
drawable 


Draws multiple points in the specified 
drawable 


Draws the outline of a single rectangle 
in the specified drawable 


Draws the outline of multiple rectangles 
in the specified drawable 


Draws multiple but not necessarily 
connected lines in the specified 
drawable 


Draws 8-bit characters in the specified 
drawable 


Draws 2-byte characters in the 
specified drawable 
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Xlib Function 


DRAW TEXT 


DRAW TEXT 16 


ENABLE ACCESS CONTROL 


FETCH BYTES 
FETCH NAME 
FILL ARC 


FILL ARCS 

FILL POLYGON 

FILL RECTANGLE 

FILL RECTANGLES 
FORCE SCREEN SAVER 
FREE COLORMAP 
FREE COLORS 


FREE CURSOR 
FREE FONT 


FREE GC 
FREE PIXMAP 


GET ATOM NAME 


GET FONT PATH 
GET GEOMETRY 


GET ICON SIZES 


GET IMAGE 
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Protocol Request 


POLY TEXT 8 
POLY TEXT 16 


SET ACCESS CONTROL 
GET PROPERTY 

GET PROPERTY 

POLY FILL ARC 


POLY FILL ARC 

FILL POLY 

POLY FILL RECTANGLE 
POLY FILL RECTANGLE 
FORCE SCREEN SAVER 
FREE COLOR MAP 
FREE COLOR 


FREE CURSOR 
CLOSE FONT 


FREE GC 
FREE PIXMAP 


GET ATOM NAME 


GET FONT PATH 
GET GEOMETRY 


GET PROPERTY 


GET IMAGE 


Description 


Draws 8-bit characters in the specified 
drawable 


Draws 2-byte characters in the 
specified drawable 


Enables access control for a display 
Returns data from cut buffer 0 
Gets the name of a window 


Fills a single arc in the specified 
drawable 


Fills multiple arcs in the specified 
drawable 


_ Fills a polygon area in the specified 


drawable 


Fills a single rectangular area in the 
specified drawable 


Fills multiple rectangular areas in the 
specified drawable 


Activates the screen saver in the 
specified mode 


Deletes the association between the 
color map resource ID and the color 
map 


Frees color map cells 
Frees (destroys) the specified cursor 


Unloads the font and frees the storage 
used by the font data structure that 
was allocated by QUERY FONT and 
LOAD QUERY FONT 


Frees the specified graphics context 


Frees all storage associated with a 
specified pixmap 

Returns a name for the specified atom 
identifier 

Gets the current font search path 


Obtains the current geometry of the 
specified drawable 


Returns the value of the icon sizes 
atom 


Returns the contents of a rectangle in 
the specified drawable on the display 
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Xlib Function 


GET INPUT FOCUS 

GET KEYBOARD CONTROL 
GET KEYBOARD MAPPING 
GET MODIFIER MAPPING 
GET MOTION EVENTS 
GET NORMAL HINTS 


GET POINTER CONTROL 


GET POINTER MAPPING 


GET SCREEN SAVER 
GET SELECTION OWNER 
GET SIZE HINTS 


GET WM HINTS 

GET WINDOW ATTRIBUTES 
GET WINDOW PROPERTY 
GET ZOOM HINTS 


GRAB BUTTON 
GRAB KEY 


GRAB KEYBOARD 


GRAB POINTER 
GRAB SERVER 


Protocol Request 


GET INPUT FOCUS 

GET KEYBOARD CONTROL 
GET KEYBOARD MAPPING 
GET MODIFIER MAPPING 
GET MOTION EVENTS 
GET PROPERTY 


GET POINTER CONTROL 


GET POINTER MAPPING 


GET SCREEN SAVER 
GET SELECTION OWNER 
GET PROPERTY 


GET PROPERTY 
GET WINDOW ATTRIBUTES 
GET GEOMETRY 
GET PROPERTY 


GET PROPERTY 


GRAB BUTTON 
GRAB KEY _ 


GRAB KEYBOARD 


GRAB POINTER 
GRAB SERVER 


Description 


Obtains information about the current 
input focus 


Obtains the current control values for 
the keyboard 


Returns the key symbols for one or 
more than one key code 


Returns the key codes for the modifier 
keys 


Gets the motion history for a specified 
window and time 


Returns the size hints for a window in 
its normal state 


Returns the pointer movement values 
for acceleration and the threshold 

at which the acceleration should be 
applied 


Returns the mapping list that defines 
which buttons are enabled for the 
pointer device 


Gets the current screen saver values 
Returns the selection owner 


Reads the value of any property of 
type WM_SIZE_HINTS 


Reads the value of the window 
manager hints atom 


Obtains the current attributes or 
geometry of a specified window 


Obtains the atom type and property 
format of a specified window 


Reads the value of the zoom hints 
atom 


Grabs a pointer button 


Passively grabs one key and specifies 
the processing of the key event 


Actively grabs control of the main 
keyboard 


Actively grabs the specified pointer 


Takes exclusive possession of the 
server associated with the display 
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Xlib Function Protocol Request Description 

INIT EXTENSION QUERY EXTENSION Allocates storage for maintaining 
the information about the extension 
on the connection, chains this onto 
the extension list, and returns the 
information the stub implementor 
needs to access the extension 

INSTALL COLORMAP INSTALL COLORMAP Installs the specified color map for its 

. associated screen 

INTERN ATOM INTERN ATOM Returns an atom for a specified name 

KILL CLIENT KILL CLIENT Disconnects a client associated with 
the specified resource 

LIST EXTENSIONS LIST EXTENSIONS Returns a list of all extensions 

supported by the server 
LIST FONTS LIST FONTS Returns a list of the available font 


LIST FONTS WITH INFO 

LIST HOSTS 

LIST INSTALLED COLORMAPS 
LIST PROPERTIES 


LOAD FONT 
LOAD QUERY FONT 


LOOKUP COLOR 
LOWER WINDOW 


MAP RAISED 
MAP SUBWINDOWS 


MAP WINDOW 
MOVE RESIZE WINDOW 
MOVE WINDOW 


NO OP 


OPEN DISPLAY — 
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LIST FONTS WITH INFO 

LIST HOSTS 

LIST INSTALLED COLORMAPS 
LIST PROPERTIES 

OPEN FONT 


OPEN FONT 
QUERY FONT 


LOOKUP COLOR 
CONFIGURE WINDOW 


CONFIGURE WINDOW 
MAP WINDOW 
MAP SUBWINDOWS 


MAP WINDOW 
CONFIGURE WINDOW 
CONFIGURE WINDOW 


NO OPERATION 


CREATE GC 


names 


Obtains the names and information 
about loaded fonts 


Returns the list of hosts that can 
access a display 


Returns a colormap identifier of each 
installed color map for a window 


Obtains the specified window's 
property list 
Loads the specified font 


Performs a LOAD FONT and QUERY 
FONT in a single operation 


Looks up the name of a color 


Lowers a window so that it does not 
obscure any sibling window 


Maps and raises a window 


Maps all subwindows for a specified 
window 


Maps the specified window 

Changes size and location of a window 
Moves a window without changing its 
size 

Sends a NoOperation request to the 
server 

Opens a connection to the server 
controlling the specified display 
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Xlib Function 


PARSE COLOR 
PUT IMAGE 


QUERY BEST CURSOR 
QUERY BEST SIZE 


QUERY BEST STIPPLE 
QUERY BEST TILE 
QUERY COLOR 


QUERY COLORS 


QUERY EXTENSION 


QUERY KEYMAP 


QUERY POINTER 


QUERY TEXT EXTENTS 


QUERY TEXT EXTENTS 16 


QUERY TREE 


RAISE WINDOW 


RECOLOR CURSOR 


REMOVE FROM SAVE SET 


REMOVE HOST 


REMOVE HOSTS 


REPARENT WINDOW 


Routines Requiring Protocol Requests 


Protocol Request 


LOOKUP COLOR 
PUT IMAGE 


QUERY BEST SIZE 
QUERY BEST SIZE 


QUERY BEST SIZE 
QUERY BEST SIZE 
QUERY COLORS 


QUERY COLORS 


QUERY EXTENSION 


QUERY KEYMAP 


QUERY POINTER 


QUERY TEXT EXTENTS 


QUERY TEXT EXTENTS 


QUERY TREE 


CONFIGURE WINDOW 
RECOLOR CURSOR 
CHANGE SAVE SET 
CHANGE HOSTS 
CHANGE HOSTS 


REPARENT WINDOW 


Description 


Parses color values 


Combines an image in memory with a 
rectangle of a drawable on the display 


Determines useful cursor sizes 


Obtains the best size of a tile, stipple, 
or cursor 


Obtains the best stipple shape 
Obtains the fill tile shape 


Queries the RGB values of a single 
specified pixel value 


Queries the RGB values of an array 
of pixels stored in the color data 
structures 


' Determines if the named extension 


is present and, if so, returns major 
opcode for the extension 


Returns a bit vector that describes that 
state of the keyboard 


Obtains the root window the pointer 
is currently on and the pointer 
coordinates relative to the root's 
origin 

Queries the server for the bounding 
box of a 1-byte character string 


Queries the server for the bounding 
box of a 2-byte character string in the 
specified font 


Obtains a list of children, the parent, 
and number of children for a specified 
window 


Raises a window so that no sibling 
window obscures it 


Changes the color of the specified 
cursor 


Removes the specified window from 
the client’s save set 


Removes a host from the list of hosts 
that can connect to a display 


Removes multiple hosts from the list of 
hosts that can connect to a display 


Changes a window’s parent to another 
window on the same screen 
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Xlib Function 


RESET SCREEN SAVER 
RESIZE WINDOW 


RESTACK WINDOWS 


ROTATE BUFFERS 
ROTATE WINDOW PROPERTIES 


SELECT INPUT 

SEND EVENT 

SET ACCESS ‘CONTROL 
SET ARC MODE 

SET BACKGROUND 


SET CLIP MASK 


SET CLIP ORIGIN 


SET CLIP RECTANGLES 


SET CLOSE DOWN MODE 
SET COMMAND 

SET DASHES 

SET FILL RULE 

SET FILL STYLE 

SET FONT 


SET FONT PATH 
SET FOREGROUND 
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Protocol Request 


FORCE SCREEN SAVER 
CONFIGURE WINDOW 


CONFIGURE WINDOW 


ROTATE PROPERTIES 
ROTATE PROPERTIES 


CHANGE WINDOW 
ATTRIBUTES 


SEND EVENT 
SET ACCESS CONTROL 


CHANGE GC 
CHANGE GC 


CHANGE GC 


CHANGE GC 


SET CLIP RECTANGLES 


SET CLOSE DOWN MODE 
CHANGE PROPERTY 
SET DASHES 

CHANGE GC 

CHANGE GC 

CHANGE GC 


SET FONT PATH 
CHANGE GC 


Description 


Resets the screen saver 


Changes a window's size without 
changing the upper left coordinate 


Restacks a set of windows from top to 
bottom 


Rotates the cut buffers 


Rotates properties in the properties 
array 


Requests server to report events 
associated with the event masks 
passed to the event_mask argument 


Sends an event to a specified window 


Changes the access control mode of a 
display to enabled or disenabled 


Sets the arc mode of the specified 
graphics context 


Sets the background of the specified 
graphics context 


Sets the clip_mask of the specified 
graphics context to the specified 
pixmap 

Sets the clip origin of the specified 
graphics context 


Sets the clip_mask of the specified 
context to the specified list of 
rectangles 


Defines what happens to a client's 
resources when the client disconnects 


Sets the value of the command atom 


Sets the dash_offset and dash_list 
for dashed line styles of the specified 
graphics context 


Sets the fill rule of the specified 
graphics context 


Sets the fill style of the specified 
graphics context 


Sets the current font of the specified 
graphics context 


Sets the font search path 
Sets the foreground of the specified 
graphics context 
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Xlib Function 
SET FUNCTION 


SET GRAPHICS EXPOSURES 


SET ICON SIZES 
SET INPUT FOCUS 


SET LINE ATTRIBUTES 
SET MODIFIER MAPPING 
SET NORMAL HINTS 
SET POINTER MAPPING 
SET PLANE MASK 


SET SCREEN SAVER 
SET SELECTION OWNER 
SET SIZE HINTS 


SET STANDARD PROPERTIES 


SET STATE 


SET STIPPLE 


SET SUBWINDOW MODE 


SET TILE 


SET TS ORIGIN 


SET WM HINTS 


SET WINDOW BACKGROUND 


SET WINDOW BACKGROUND 
PIXMAP 


Protocol Request 


CHANGE GC 
CHANGE GC 


CHANGE PROPERTY 
SET INPUT FOCUS 


CHANGE GC 

SET MODIFIER MAPPING 
CHANGE PROPERTY 
SET POINTER MAPPING 
CHANGE GC 


SET SCREEN SAVER 
SET SELECTION OWNER 
CHANGE PROPERTY 


CHANGE PROPERTY 


CHANGE GC 


CHANGE GC 
CHANGE GC 
CHANGE GC 
CHANGE GC 
CHANGE PROPERTY 
CHANGE WINDOW 


ATTRIBUTES 


CHANGE WINDOW 
ATTRIBUTES 


Description 


Sets the display function in the 
specified graphics context 


Sets the graphics exposures flag of the 
specified graphics context 


Sets the value of the icon size atom 


Changes the input focus to the 
specified window 


Sets the line drawing components of 
the specified graphics context 


Specifies the key codes for the modifier 
keys 


Sets the size hints for a window in its 
normal state 


Enables or disables buttons for the 
pointer 


Sets the plane mask of the specified 
graphics context 


Sets the screen saver 
Sets the selection owner 


Sets the value of any property of type 
WM_SIZE_HINTS 


Specifies a minimum set of properties 
describing a simple application 


Sets the foreground, background, 
plane mask, and function components 
for the specified graphics context 


Sets the stipple of the specified 
graphics context 


Sets the subwindow mode of the 
specified graphics context 


Sets the fill tile of the specified 
graphics context 


Sets the tile or stipple origin of the 
specified graphics context 


Sets the value of the window manager 
hints atom 


Sets the background of a specified 
window to the specified pixel 


Sets the background of a specified 
window to the specified pixmap 
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Xlib Function 


Protocol Request — 


Description — 





SET WINDOW BORDER 


SET WINDOW BORDER PIXMAP 


SET WINDOW BORDER WIDTH 


SET WINDOW COLORMAP 


SET ZOOM HINTS 
STORE BUFFER 
STORE BYTES 
STORE COLOR 


STORE COLORS 
STORE NAME 
STORE NAMED COLOR 


SYNC 


TRANSLATE COORDINATES 


UNDEFINE CURSOR 


UNGRAB BUTTON 


UNGRAB KEY 


UNGRAB KEYBOARD 


UNGRAB POINTER 


UNGRAB SERVER 


UNINSTALL COLORMAP 
UNLOAD FONT 


UNMAP SUBWINDOWS 


UNMAP WINDOW 
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CHANGE WINDOW 
ATTRIBUTES 


CHANGE WINDOW _ 
ATTRIBUTES 


CONFIGURE WINDOW 


CHANGE WINDOW 
ATTRIBUTES 


CHANGE PROPERTY 
CHANGE PROPERTY 
CHANGE PROPERTY 
STORE COLORS 


STORE COLORS 
CHANGE PROPERTY 
STORE NAMED COLOR 


GET INPUT FOCUS 
TRANSLATE COORDINATES 


CHANGE WINDOW 
ATTRIBUTES 
UNGRAB BUTTON 
UNGRAB KEY 
UNGRAB KEYBOARD 
UNGRAB POINTER 


UNGRAB SERVER 


UNINSTALL COLORMAP 
CLOSE FONT 


UNMAP SUBWINDOWS 


UNMAP WINDOW 


Changes and repaints a window’s 
border to the specified pixel 


Changes and repaints a window's 
border tile 


Changes the border width of a window 


Sets the color map of a specified 
window 


Sets the value of the zoom hints atom 
Stores data in specified cut buffer 
Stores data in cut buffer zero 


Stores an RGB value into a single 
color map cell 


Stores RGB values into color map cells 
Assigns a name to a window 


Sets the color of a pixel to the named 
color 


Flushes the output buffer and then 
waits until all requests have been 
processed 


Performs a coordinate transformation 
from the coordinate space of one 
window to another window 


Removes the association of the cursor 
with the specified window 


Deactivates the passive grab for a 
pointer device button press 


Releases the key combination on the 
specified window that was grabbed 


Releases an active grab on the main 
keyboard 


Releases an active grab on the 
specified pointer 


Relinquishes exclusive possession of 
the server 


Uninstalls a color map for a screen 


Unioads the specified font that was 
loaded by LOAD FONT 


Unmaps all subwindows for a specified 
window 


Unmaps a window 


(continued on next page) 


Routines Requiring Protocol Requests 


Table B-1 (Cont.) Routines Requiring Protocol Requests 
Xlib Function Protocol Request Description 


WARP POINTER WARP POINTER Moves the pointer to any specified 
location on the screen 
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C VMS DECwindows Named Colors 


Table C—1 lists available VMS DECwindows named colors. The table 
provides the color name and the RGB values associated with that color. 
For a description of using named colors, see Section 5.3.1. Note that color 
display is device dependent. Entering the RGB values for a specific named 
color may not display that color. 


Table C-1 VMS DECwindows Named Colors 


Named Color nee values 
Red Green Biue 

Aquamarine 28784 56283 37779 
Medium Aquamarine 12850 52428 39321 
MediumAquamarine 12850 52428 39321 
Black 0 . 0 0 
Blue 0 0 65535 
Cadet Blue 24415 40863 40863 
CadetBlue 24415 40863 40863 
Cornflower Blue 16962 16962 28527 
CornflowerBlue 16962 16962 28527 
Dark Slate Blue 27499 8995 36494 
DarkSlateBlue 27499 8995 36494 
Light Blue 49087 56512 55512 
LightBlue 49087 55512 56512 
Light Steel Blue 36751 36751 48316 
LightSteelBlue 36751 36751 48316 
Medium Blue 12850 12850 52428 
MediumBlue 12850 12850 52428 
Medium Slate Blue 32639 0 65535 
MediumSlateBlue 32639 0 65535 
Midnight Blue 12079 12079 20303 
MidnightBlue 12079 12079 20303 
Navy Blue 8995 8995 36494 
NavyBlue 8995 8995 36494 
Navy 8995 8995 36494 
Sky Blue 12850 39321 52428 
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Named Color GE Wale? 

Red Green Biue 
SkyBlue 12850 39321 52428 
Slate Blue 0 32639 65535 
SlateBlue 0 32639 65535 
Steel Blue 8995 27499 36494 
SteelBlue 8995 27499 36494 
Coral 65535 32639 0 
Cyan 0 65535 65535 
Firebrick 36494 8995 8995 
Brown 42405 10794 10794 
Sandy Brown 62708 42148 24672 
SandyBrown 62708 42148 24672 
Gold 52428 32639 12850 
Goldenrod 56283 56283 28784 
Medium Goldenrod 60138 60138 44461 
MediumGoldenrod 60138 60138 44461 
Green 0 65535 0 
Dark Green 12079 20303 12079 
DarkGreen 12079 20303 12079 
Dark Olive Green 20303 20303 12079 
DarkOliveGreen 20303 20303 12079 
Forest Green 8995 36494 8995 
ForestGreen 8995 36494 8995 
Lime Green 12850 52428 12850 
LimeGreen 12850 52428 12850 
Medium Forest Green 27499 36494 8995 
MediumForestGreen 27499 36494 8995 
Medium Sea Green 16962 28527 16962 
MediumSeaGreen 16962 28527 16962 
Medium Spring Green 32639 65535 0 
MediumSpringGreen 32639 65535 0 
Pale Green 36751 48316 36751 
PaleGreen 36751 48316 36751 
Sea Green 8995 36494 27499 
SeaGreen 8995 36494 27499 
Spring Green 0. 65535 32639 
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Named Color GB values 
Red Green Biue 

SpringGreen 0 65535 32639 
Yellow Green 39321 52428 12850 
YellowGreen 39321 52428 12850 
Dark Slate Grey 12079 20303 20303 
DarkSlateGrey 12079 20303 20303 
Dark Slate Gray 12079 20303 20303 
DarkSlateGray 12079 20303 20303 
Dim Grey 21588 21588 21588 
DimGrey 21588 21588 21588 
Dim Gray 21588 21588 21588 
DimGray 21588 21588 21588 
Light Grey 43176 43176 43176 
LightGrey 43176 43176 43176 
Light Gray 43176 43176 43176 
LightGray 43176 43176 43176 
Gray 49344 49344 49344 
Grey 49344 49344 49344 
Khaki 40863 40863 24415 
Magenta 65535 0 65535 
Maroon 36494 8995 27499 
Orange - §2428 12850 12850 
Orchid 56283 28784 — §6283 
Dark Orchid 39321 12850 52428 
DarkOrchid 39321 12850 52428 
Medium Orchid 37779 28784 56283 
MediumOrchid 37779 28784 56283 
Pink 48316 36751 36751 
Plum 60138 | 44461 60138 
Red 65535 0 0 
Indian Red 20303 12079 12079 
IndianRed 20303 12079 12079 
Medium Violet Red 56283 28784 37779 
MediumVioletRed 56283 28784 37779 
Orange Red 65535 0 32639 
OrangeRed 65535 0 32639 
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Named Color AGE valuce 

Red Green Blue 
VioletRed 52428 12850 39321 
Salmon 28527 © 16962 16962 
Sienna 36494 27499 8995 
Tan 56283 37779 28784 
Thistle 55512 49087 55512 
Turquoise 44461 60138 60138 
Dark Turquoise 28784 37779 56283 
DarkTurquoise 28784 37779 56283 
Medium Turquoise 28784 56283 56283 
MediumTurquoise 28784 56283 56283 
Violet 20303 12079 20303 
Blue Violet 40863 24415 40863 
BiueViolet 40863 24415 40863 
Wheat 55512 55512 49087 
White 65535 65535 65535 
Yellow 65535 65535 0 
Green Yellow 37779 56283 28784 
GreenYellow 37779 56283 28784 
GrayO 0 0 0 
Gray1 771 771 771 
Gray2 1285 1285 1285 
Gray3 2056 2056 2056 
Gray4 2570 2570 2570 
Gray5 3341 3341 3341 
Gray6 3855 3855 3855 
Gray7 4626 4626 4626 
Gray8 5140 5140 5140 
Gray9 5911 5911 5911 
Gray10 6682 6682 6682 
Gray11 7196 7196 7196 
Gray12 7967 7967 7967 
Gray13 8481 8481 8481 
Gray14 9252 9252 9252 
Gray15 9766 9766 9766 
Gray1i6 10537 10537 10537 
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Named Color RGB Values 
Red Green Blue 

Gray17 11051 11051 11051 
Gray18 11822 11822 11822 
Gray19 12336 12336 12336 
Gray20 13107 13107 13107 
Gray21 13878 13878 13878 
Gray22 14392 14392 14392 
Gray23 15163 15163 15163 
Gray24 15677 15677 15677 
Gray25 16448 16448 16448 
Gray26 16962 16962 16962 
Gray27 17733 17733 17733 
Gray28 18247 18247 18247 
Gray29 19018 19018 19018 
Gray30 19789 19789 19789 
Gray31 20303 20303 20303 
Gray32 21074 21074 21074 
Gray33 21588 21588 21588 
Gray34 22359 22359 22359 
Gray35 22873 22873 22873 
Gray36 23644 23644 23644 
Gray37 24158 24158 24158 
Gray38 24929 24929 24929 
Gray39 25443 25443 25443 
Gray40 26214 26214 26214 
Gray41 26985 26985 26985 
Gray42 27499 27499 27499 
Gray43 28270 28270 28270 
Gray44 28784 28784 28784 
Gray45 29555 29555 29555 
Gray46 30069 30069 30069 
Gray47 30840 30840 30840 
Gray48 31354 31354 31354 
Gray49 32125 32125 32125 
Gray50 32639 32639 32639 
Gray51 33410 33410 33410 
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Named Color ne values 

| Red Green Blue 
Gray52 34181 34181 34181 
Gray53 34695 34695 34695 
Gray54 35466 35466 35466 
Gray55 35980 35980 35980 
Gray56 36751 36751 36751 
Gray57 37265 37265 37265 
Gray58 38036 38036 38036 
Gray59 38550 38550 38550 
Gray60 39321 39321 39321 
Gray61 40092 40092 40092 
Gray62 40606 40606 40606 
Gray63 41377 41377 41377 
Gray64 41891 41891 41891 
Gray65 42662 42662 42662 
Gray66 43176 43176 43176 
Gray67 43947 43947 43947 
Gray68 44461 44461 44461 
Gray69 45232 45232 45232 
Gray70 46003 46003 46003 
Gray71 46517 46517 46517 
Gray72 47288 47288 47288 
Gray73 47802 47802 47802 
Gray74 48573 48573 48573 
Gray75 49087 49087 49087 
Gray76 49858 49858 49858 
Gray77 50372 50372 50372 
Gray78 51143 51143 51143 
Gray79 51657 51657 51657 
Gray80 52428 52428 52428 
Gray81 53199 53199 53199 
Gray82 53713 53713 53713 
Gray83 54484 54484 54484 
Gray84 54998 54998 54998 
Gray85 55769 55769 55769 
Gray86 56283 56283 56283 
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Named Color . Ge Yauee 

Red Green Blue 
Gray87 57054 57054 57054 
Gray88 57568 57568 57568 
Gray89 58339 58339 58339 
Gray90 58853 58853 58853 
Gray91 59624 — 59624 59624 
Gray92 60395 60395 60395 
Gray93 60909 60909 60909 
Gray94 61680 61680 61680 
Gray95 62194 62194 62194 
Gray96 62965 62965 62965 
Gray97. 63479 63479 63479 
Gray98 - 64250 64250 64250 
Gray99 64764 64764 64764 
Gray100 65535 65535 65535 
Grey0 0 0 0 
Grey1 771 771 771 
Grey2 . 1285 1285 1285 
Grey3 2056 2056 2056 
Grey4 2570 | 2570 2570 
Grey5 3341 3341 3341 
Grey6 3855 3855 3855 
Grey7 4626 4626 4626 
Grey8 5140 5140 5140 
Grey9 5911 5911 5911 
Grey10 6682 6682 6682 
Grey11 7196 7196 7196 
Grey12 7967 7967 7967 
Grey13 8481 8481 8481 
Grey14 9252 9252 9252 
Grey15 9766 9766 9766 
Grey16 10537 10537 10537 
Grey17 11051 11051 11051 
Grey18 11822 11822 11822 
Grey19 12336 12336 12336 


Grey20 13107 | 13107 13107 
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Named Color GE veues 
Red Green Blue 

Grey21 ~ 13878 13878 13878 
Grey22 14392 14392 14392 
Grey23 15163 15163 15163 
Grey24 15677 15677 15677 
Grey25 16448 16448 16448 
Grey26 16962 16962 16962 
Grey27 17733 17733 17733 
Grey28 18247 18247 18247 
Grey29 19018 19018 19018 
Grey30 . 19789. 19789 19789 
Grey31 20303 20303 20303 
Grey32 21074 21074 21074 
Grey33 21588 21588 21588 
Grey34 22359 22359 22359 
Grey35 22873 22873 22873 
Grey36 23644 23644 23644 
Grey37 24158 24158 24158 
Grey38 24929 24929 24929 
Grey39 25443 25443 25443 
Grey40 26214 26214 26214 
Grey41 26985. 26985 26985 
Grey42 27499 27499 27499 
Grey43 28270 28270 28270 
Grey44 28784 . 28784 28784 
Grey45 29555 29555 29555 
Grey46 30069. 30069 30069 
Grey47 30840 30840 30840 
Grey48 31354 31354 31354 
Grey49 32125 32125 32125 
Grey50- 32639 32639 32639 
Grey51.. 33410 33410 33410 
Grey52 34181 34181 34181 
Grey53 34695 34695 34695 
Grey54 35466 35466 35466 
Grey55 35980 35980 35980 
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Named Color RGB Values 

Red Green Blue 
Grey56 36751 36751 36751 
Grey57 37265 37265 37265 
Grey58 38036 38036 38036 
Grey59 38550 38550 38550 
Grey60 39321 39321 39321 
Grey61 40092 40092 40092 
Grey62 40606 40606 40606 
Grey63 41377 41377 41377 
Grey64 41891 41891 41891 
Grey65 42662 42662 42662 
Grey66 43176 43176 43176 
Grey67 43947 43947 43947 
Grey68 44461 44461 44461 
Grey69 45232 45232 45232 
Grey70 46003 46003 46003 
Grey71 46517 46517 46517 
Grey72 47288 47288 47288 
Grey73 47802 47802 47802 
Grey74 48573 48573 48573 
Grey75 49087 49087 49087 
Grey76 49858 49858 49858 
Grey77 50372 50372 50372 
Grey78 51143 51143 51143 
Grey79 51657 51657 51657 
Grey80 52428 52428 52428 
Grey81 53199 53199 5319S 
Grey82 53713 53713 53713 
Grey83 54484 54484 54484 
Grey84 54998 54998 54998 
Grey85 55769 55769 55769 
Grey86 56283 56283 56283 
Grey87 57054 57054 57054 
Grey88 57568 57568 57568 
Grey89 58339 58339 58339 
Grey90 58853 58853 58853 
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Named Color AGE Values 
Red Green Blue 

Grey91 59624 59624 ‘59624 
Grey92 60395 60395 60395 
Grey93 60909 60909 60909 
Grey94 61680 61680 61680 
Grey95 62194 62194 62194 
Grey96 62965 62965 62965 
Grey97 63479 63479 63479 
Grey98 64250 64250 64250 
Grey99 64764 64764 64764 
Grey100 65535 65535 65535 








VMS DECwindows Fonts 


Table D-1 lists VMS DECwindows 75 DPI fonts and their file names. 
Table D-2 lists VMS DECwindows 100 DPI fonts and their file names. For 
information about using fonts, see Chapter 8. 


Note that a double dash occurs between the fifth and sixth field of the font 
name. For example, the full name of a representative font is as follows: 


-Adobe-ITC Avant Garde Gothic-Book-R-Normal--11-80~100-100-P-59-IS08859-1 


Table D-1 VMS DECwindows 75 DPI Fonts 














File Name Ae Font Name 

FIXED . —_— Fixed 

CURSOR Cursor 

DECWSCURSOR DECWSCURSOR 

DECWS$SESSION DECWS$SESSION 

VARIABLE Variable 

AVANT GARDE 

AVANTGARDE_BOOK8 -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -8-80-75-75-P-49-ISO8859-1 
AVANTGARDE_BOOK10 -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -10-100-75-75-P-59-ISO8859-1 
AVANTGARDE_BOOK12 -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -12-120-75-75-P-70-ISO8859-1 
AVANTGARDE_BOOK14 -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -14-140-75-75-P-80-ISO8859-1 
AVANTGARDE_BOOK18 -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -18-180-75-75-P-103-ISO8859-1 
AVANTGARDE_BOOK24 -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -24-240-75-75-P-138-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE8 -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -8-80-75-75-P-49-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE10 -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -10-100-75-75-P-59-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE12 -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -12-120-75-75-P-69-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE14 -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -14-140-75-75-P-81-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE18 -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -18-180-75-75-P-103-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE24 -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -24-240-75-75-P-138-ISO8859-1 
AVANTGARDE_DEMI8 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -8-80-75-75-P-51-ISO8859-1 
AVANTGARDE_DEMI10 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -10-100-75-75-P-61 -ISO8859-1 
AVANTGARDE_DEMI12 -Adobe-iTC Avant Garde Gothic-Demi-R-Normal- -12-120-75-75-P-70-ISO8859-1 
AVANTGARDE_DEMI14 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -14-140-75-75-P-82-ISO8859-1 
AVANTGARDE_DEMI18 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -18-180-75-75-P-105-ISO8859-1 
AVANTGARDE_DEMI24 ° -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -24-240-75-75-P-140-ISO8859-1 
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File Name Font Name 
AVANT GARDE 
AVANTGARDE_DEMIOBLIQUES -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -8-80-75-75-P-51-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE10 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -10-100-75-75-P-61-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE12 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -12-120-75-75-P-71-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE14 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -14-140-75-75-P-82-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE18 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -18-180-75-75-P-103-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE24 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -24-240-75-75-P-139-ISO8859-1 
COURIER 
COURIERS -Adobe-Courier-Medium-R-Normal- -8-80-75-75-M-50-ISO8859-1 
COURIER10 -Adobe-Courier-Medium-R-Normal- -10-100-75-75-M-60-ISO8859-1 
COURIER12 -Adobe-Courier-Medium-R-Normal- -12-120-75-75-M-70-ISO8859-1 
COURIER14 -Adobe-Courier-Medium-R-Normal- -14-140-75-75-M-90-ISO8859-1 
COURIER18 -Adobe-Courier-Medium-R-Normal- -18-180-75-75-M-110-ISO8859-1 
COURIER24 -Adobe-Courier-Medium-R-Normal- -24-240-75-75-M-150-ISO8859-1 
COURIER_BOLD8 -Adobe-Courier-Bold-R-Normal- -8-80-75-75-M-50-ISO8859-1 
COURIER_BOLD10 -Adobe-Courier-Bold-R-Normal- -10-100-75-75-M-60-ISO8859-1 
COURIER_BOLD12 -Adobe-Courier-Bold-R-Normal- -12-120-75-75-M-70-ISO8859-1 
COURIER_BOLD14 -Adobe-Courier-Bokd-R-Normal- -14-140-75-75-M-90-ISO8859-1 
COURIER_BOLD18 -Adobe-Courier-Bold-R-Normal- -18-180-75-75-M-110-ISO8859-1 
COURIER_BOLD24 -Adobe-Courier-Bold-R-Normal- -24-240-75-75-M-150-ISO8859-1 
COURIER_BOLDOBLIQUES -Adobe-Courier-Bold-O-Normal- -8-80-75-75-M-50-ISO8859-1 
COURIER_BOLDOBLIQUE10 -Adobe-Courier-Bold-O-Normal- -10-100-75-75-M-60-ISO8859-1 
COURIER_BOLDOBLIQUE12 -Adobe-Courier-Bold-O-Normal- -12-120-75-75-M-70-ISO8859-1 
COURIER_BOLDOBLIQUE14 -Adobe-Courier-Bold-O-Normal- -14-140-75-75-M-90-ISO8859-1 
COURIER_BOLDOBLIQUE18 -Adobe-Courier-Boid-O-Normal- -18-180-75-75-M-110-ISO8859-1 
COURIER_BOLDOBLIQUE24 -Adobe-Courier-Bold-O-Normal- -24-240-75-75-M-150-ISO8859-1 
COURIER_OBLIQUE8 -Adobe-Courier-Medium-O-Normal- -8-80-75-75-M-50-ISO8859-1 
COURIER_OBLIQUE10 -Adobe-Courier-Medium-O-Normal- -10-100-75-75-M-60-ISO8859-1 
COURIER_OBLIQUE12 -Adobe-Courier-Medium-O-Normal- -12-120-75-75-M-70-ISO8859-1 
COURIER_OBLIQUE14 -Adobe-Courier-Medium-O-Normal- -14-140-75-75-M-90-ISO8859-1 
COURIER_OBLIQUE18 -Adobe-Courier-Medium-O-Normal- -18-180-75-75-M-110-ISO8859-1 
COURIER_OBLIQUE24 -Adobe-Courier-Medium-O-Normal- -24-240-75-75-M-150-ISO8859-1 
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File Name Font Name 

HELVETICA 

HELVETICA8 -ADOBE-Helvetica-Medium-R-Normal- -8-80-75-75-P-46-ISO8859-1 
HELVETICA10 -ADOBE-Helvetica-Medium-R-Normal- -10-100-75-75-P-56-ISO8859-1 
HELVETICA12 -ADOBE-Helvetica-Medium-R-Normal- -12-120-75-75-P-67-ISO8859-1 
HELVETICA14 -ADOBE-Heivetica-Medium-R-Normal- -14-140-75-75-P-77-ISO8859-1 
HELVETICA18 -ADOBE-Heivetica-Medium-R-Normal- -18-180-75-75-P-98-ISO8859-1 
HELVETICA24 -ADOBE-Helvetica-Medium-R-Normal- -24-240-75-75-P-130-ISO8859-1 
HELVETICA_BOLD8 -ADOBE-Heivetica-Bold-R-Normal- -8-80-75-75-P-50-ISO8859-1 
HELVETICA_BOLD10 -ADOBE-Heilvetica-Bold-R-Normal- -10-100-75-75-P-60-ISO8859-1 
HELVETICA_BOLD12 -ADOBE-Helvetica-Bold-R-Normal- -12-120-75-75-P-70-ISO8859-1 
HELVETICA_BOLD14 -ADOBE-Heivetica-Bold-R-Normal- -14-140-75-75-P-82-ISO8859-1 
HELVETICA_BOLD18 -ADOBE-Helvetica-Bold-R-Normal- -18-180-75-75-P-103-ISO8859-1 
HELVETICA_BOLD24 -ADOBE-Helvetica-Bold-R-Normal- -24-240-75-75-P-138-ISO8859-1 
HELVETICA_BOLDOBLIQUES8 -ADOBE-Heivetica-Bold-O-Normal- -8-80-75-75-P-50-ISO8859-1 
HELVETICA_BOLDOBLIQUE10 -ADOBE-Helvetica-Bold-O-Normal- -10-100-75-75-P-60-ISO8859-1 
HELVETICA_BOLDOBLIQUE12 -ADOBE-Helvetica-Bold-O-Normal- -12-120-75-75-P-69-ISO8859-1 
HELVETICA_BOLDOBLIQUE14 -ADOBE-Helvetica-Bold-O-Normal- -14-140-75-75-P-82-ISO8859-1 
HELVETICA_BOLDOBLIQUE18 -ADOBE-Helvetica-Bold-O-Normal- -18-180-75-75-P-104-ISO8859-1 
HELVETICA_BOLDOBLIQUE24 -ADOBE-Helvetica-Bold-O-Normal- -24-240-75-75-P-138-ISO8859-1 
HELVETICA_OBLIQUES -ADOBE-Helvetica-Medium-O-Normal- -8-80-75-75-P-47-ISO8859-1 
HELVETICA_OBLIQUE10 -ADOBE-Helvetica-Medium-O-Normal- -10-100-75-75-P-57-ISO8859-1 
HELVETICA_OBLIQUE12 -ADOBE-Helvetica-Medium-O-Normal- -12-120-75-75-P-67-ISO8859-1 
HELVETICA_OBLIQUE14 -ADOBE-Helvetica-Medium-O-Normal- -14-140-75-75-P-78-ISO8859-1 
HELVETICA_OBLIQUE18 -ADOBE-Helvetica-Medium-O-Normal- -18-180-75-75-P-98-ISO8859-1 
HELVETICA_OBLIQUE24 -ADOBE-Helvetica-Medium-O-Normal- -24-240-75-75-P-130-ISO8859-1 
INTERIM 

INTERIM_DM_EXTENSION14 -ADOBE- Interim DM-Medium-I-Normal- -14-140-75-75-P-140-DEC-DECMATH_EXTENSION 
INTERIM_DM_ITALIC14 -ADOBE-Interim DM-Medium-I-Normal- -14-140-75-75-P-140-DEC-DECMATH_ITALIC 
INTERIM_DM_SYMBOL14 -ADOBE-Interim DM-Medium-I-Normal- -14-140-75-75-P-140-DEC-DECMATH_SYMBOL 
LUBALIN GRAPH 

LUBALINGRAPH_BOOK8 -Adobe-ITC Lubalin Graph-Book-R-Normal- -8-80-75-75-P-50-ISO8859-1 
LUBALINGRAPH_BOOK10 -Adobe-ITC Lubalin Graph-Book-R-Normal- -10-100-75-75-P-60-ISO8859-1 
LUBALINGRAPH_BOOK12 -Adobe-ITC Lubalin Graph-Book-R-Normal- -12-120-75-75-P-70-ISO8859-1 





(continued on next page) 


D-3 


VMS DECwindows Fonts 


Table D-1 (Cont.) VMS DECwindows 75 DPI Fonts 
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LUBALIN GRAPH 





LUBALINGRAPH_BOOK14 -Adobe-ITC Lubalin Graph-Book-R-Normal- -14-140-75-75-P-81-ISO8859-1 


LUBALINGRAPH_BOOK18 -Adobe-ITC Lubalin Graph-Book-R-Normal- -18-180-75-75-P-106-ISO8859-1 
LUBALINGRAPH_BOOK24 -Adobe-ITC Lubalin Graph-Book-R-Normal- -24-240-75-75-P-139-ISO8859-1 
LUBALINGRAPH_BOOKOBLIQUE8 -Adobe-ITC Lubalin Graph-Book-O-Normal- -8-80-75-75-P-50-ISO8859-1 
LUBALINGRAPH_BOOKOBLIQUE10 -Adobe-ITC Lubalin Graph-Book-O-Normal- -10-100-75-75-P-60-ISO8859-1 
LUBALINGRAPH_BOOKOBLIQUE 12 -Adobe-ITC Lubalin Graph-Book-O-Normal- -12-120-75-75-P-70-ISO8859-1 
LUBALINGRAPH_BOOKOBLIQUE14 -Adobe-ITC Lubalin Graph-Book-O-Normal- -14-140-75-75-P-82-ISO8859-1 
LUBALINGRAPH_BOOKOBLIQUE18 -Adobe-ITC Lubalin Graph-Book-O-Normal- -18-180-75-75-P-105-ISO8859-1 


LUBALINGRAPH_BOOKOBLIQUE24 -Adobe-ITC Lubalin Graph-Book-O-Normal- -24-240-75-75-P-140-ISO8859-1 


LUBALINGRAPH_DEMI8 -Adobe-ITC Lubalin Graph-Demi-R-Normal- -8-80-75-75-P-51-ISO8859-1 
LUBALINGRAPH_DEMI10 -Adobe-ITC Lubalin Graph-Demi-R-Normal- -10-100-75-75-P-61-ISO8859-1 
LUBALINGRAPH_DEMI12 -Adobe-ITC Lubalin Graph-Demi-R-Normal- -12-120-75-75-P-73-ISO8859- 1 
LUBALINGRAPH_DEMI14 -Adobe-ITC Lubalin Graph-Demi-R-Normal- -14-140-75-75-P-85-ISO8859-1 
LUBALINGRAPH_DEMI18 -Adobe-ITC Lubalin Graph-Demi-R-Normal- -18-180-75-75-P-109-ISO8859-1 
LUBALINGRAPH_DEMI24 -Adobe-ITC Lubalin Graph-Demi-R-Normal- -24-240-75-75-P-144-ISO8859-1 


LUBALINGRAPH_DEMIOBLIQUE8 -Adobe-ITC Lubalin Graph-Demi-O-Normal- -8-80-75-75-P-52-ISO8859-1 - 


LUBALINGRAPH_DEMIOBLIQUE10 -Adobe-ITC Lubalin Graph-Demi-O-Normal- -10-100-75-75-P-62-ISO8859-1 
LUBALINGRAPH_DEMIOBLIQUE12 -Adobe-ITC Lubalin Graph-Demi-O-Normal- -12-120-75-75-P-74-ISO8859-1 
LUBALINGRAPH_DEMIOBLIQUE14 -Adobe-ITC Lubalin Graph-Demi-O-Normal- -14-140-75-75-P-85-ISO8859-1 
LUBALINGRAPH_DEMIOBLIQUE18 -Adobe-ITC Lubalin Graph-Demi-O-Normal- -18-180-75-75-P-109-ISO8859-1 


LUBALINGRAPH_DEMIOBLIQUE24 -Adobe-ITC Lubalin Graph-Demi-O-Normal- -24-240-75-75-P-144-ISO8859-1 











MENU 

MENU10 -Bigelow & Holmes-Menu-Medium-R-Normal- -10-100-75-75-P-56-ISO8859-1 
MENU12 -Bigelow & Holmes-Menu-Medium-R-Normal- -12-120-75-75-P-70-ISO8859-1 
NEW CENTURY SCHOOLBOOK 





NEWCENTURYSCHLBK_BOLD8 

NEWCENTURYSCHLBK_BOLD10 
NEWCENTURYSCHLBK_BOLD12 
NEWCENTURYSCHLBK_BOLD14 
NEWCENTURYSCHLBK_BOLD18 


NEWCENTURYSCHLBK_BOLD24 


NEWCENTURYSCHLBK_BOLDITALIC8 


-Adobe-New Century Schoolbook-Bold-R-Normal- -8-80-75-75-P-56-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal- -10-100-75-75-P-66-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal- -12-120-75-75-P-77-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal- -14-140-75-75-P-87-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal- -18-180-75-75-P-113-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal- -24-240-75-75-P-149-ISO8859-1 


-Adobe-New Century Schoolbook-Bold-I-Normal- -8-80-75-75-P-56-ISO8859-1 





I 
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NEW CENTURY SCHOOLBOOK 





NEWCENTURYSCHLBK_BOLDITALIC10 -Adobe-New Century Schoolbook-Bold-I-Normal- -10-100-75-75-P-66-ISO8859-1 


NEWCENTURYSCHLBK._BOLDITALIC12 -Adobe-New Century Schoolbook-Bold-I-Normal- -12-120-75-75-P-76-ISO8859-1 
NEWCENTURYSCHLBK_BOLDITALIC14 -Adobe-New Century Schoolbook-Bold-I-Normal- -14-140-75-75-P-88-ISO8859-1 
NEWCENTURYSCHLBK_BOLDITALIC18 -Adobe-New Century Schoolbook-Bold-I-Normal- -18-180-75-75-P-111 -ISO8859-1 


NEWCENTURYSCHLBK_BOLDITALIC24 -Adobe-New Century Schoolbook-Bold-I-Normal- -24-240-75-75-P-148-ISO8859-1 


NEWCENTURYSCHLBK_ITALIC8 
NEWCENTURYSCHLBK_ITALIC10 
NEWCENTURYSCHLBK_ITALICi2 
NEWCENTURYSCHLBK_ITALIC14 
NEWCENTURYSCHLBK_ITALIC18 
NEWCENTURYSCHLBK_ITALIC24 
NEWCENTURYSCHLBK_ROMANS 
NEWCENTURYSCHLBK_ROMAN10 
NEWCENTURYSCHLBK_ROMAN12 
NEWCENTURYSCHLBK_ROMAN14 
NEWCENTURYSCHLBK_ROMAN18 


NEWCENTURYSCHLBK_ROMAN24 


-Adobe-New Century Schoolbook-Medium-I-Normal- -8-80-75-75-P-50-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-I-Normal- -10-100-75-75-P-60-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-!-Normal- -12-120-75-75-P-70-ISO8859-1 © 
~Adobe-New Century Schoolbook-Medium-I-Normal- -14-140-75-75-P-81-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-!-Normal- -18-180-75-75-P-104-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-I-Normal- -24-240-75-75-P-136-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-R-Normal- -8-80-75-75-P-50-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-R-Normal- -10-100-75-75-P-60-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-R-Normal- -12-120-75-75-P-70-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-R-Normal- -14-140-75-75-P-82-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-R-Normal- -18-180-75-75-P-103-ISO8859-1 


-Adobe-New Century Schoolbook-Medium-R-Normai- -24-240-75-75-P-137-ISO8859-1 





SOUVENIR 





SOUVENIR_DEMI8 
SOUVENIR_DEMI10 
SOUVENIR_DEMI12 
SOUVENIR_DEMI14 
SOUVENIR_DEMI18 
SOUVENIR_DEMI24 
SOUVENIR_DEMIITALIC8 
SOUVENIR_DEMITALIC10 
SOUVENIR_DEMIITALIC12 
SOUVENIR_DEMIITALIC14 
SOUVENIR_DEMIITALIC18 
SOUVENIR_DEMIITALIC24 
SOUVENIR_LIGHTS 
SOUVENIR_LIGHT10 
SOUVENIR_LIGHT12 


SOUVENIR_LIGHT14 


-Adobe-ITC Souvenir-Demi-R-Normal- -8-80-75-75-P-52-ISO8859-1 
-Adobe-!ITC Souvenir-Demi-R-Normal- -10-100-75-75-P-62-ISO8859-1 
-Adobe-ITC Souvenir-Demi-R-Normal- -12-120-75-75-P-75-ISO8859-1 
-Adobe-ITC Souvenir-Demi-R-Normal- -14-140-75-75-P-90-ISO8859-1 
-Adobe-ITC Souvenir-Demi-R-Normal- -18-180-75-75-P-112-ISO8859-1 
-Adobe-ITC Souvenir-Demi-R-Normal- -24-240-75-75-P-149-ISO8859-1 
-Adobe-ITC Souvenir-Demi-l-Normal- -8-80-75-75-P-57-ISO8859-1 
-Adobe-ITC Souvenir-Demi-l-Normal- -10-100-75-75-P-67-ISO8859-1 
-Adobe-ITC Souvenir-Demi-I-Normal- -12-120-75-75-P-78-ISO8859-1 
-Adobe-ITC Souvenir-Demi-l-Normal- -14-140-75-75-P-92-ISO8859-1 
-Adobe-ITC Souvenir-Demi-I-Normal- -18-180-75-75-P-115-ISO8859-1 . 
-Adobe-ITC Souvenir-Demi-l-Normal- -24-240-75-75-P-154-ISO8859-1 
-Adobe-ITC Souvenir-Light-R-Normal- -8-80-75-75-P-46-ISO8859-1 
-Adobe-ITC Souvenir-Light-R-Normal- -10-100-75-75-P-56-ISO8859-1 
-Adobe-ITC Souvenir-Light-R-Normal- -12-120-75-75-P-68-ISO8859-1 


-Adobe-iITC Souvenir-Light-R-Normal- -14-140-75-75-P-79-ISO8859-1 
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Font Name 








SOUVENIR_LIGHT18 
SOUVENIR_LIGHT24 
SOUVENIR_LIGHTITALIC8 
SOUVENIR_LIGHTITALIC10 
SOUVENIR_LIGHTITALIC12 
SOUVENIR_LIGHTITALIC14 
SOUVENIR_LIGHTITALIC18 


SOUVENIR_LIGHTITALIC24 


-Adobe-ITC Souvenir-Light-R-Normal- -18-180-75-75-P-102-ISO8859-1 
-Adobe-ITC Souvenir-Light-R-Normal- -24-240-75-75-P-135-ISO8859-1 
-Adobe-ITC Souvenir-Light-I-Normal- -8-80-75-75-P-49-ISO8859-1 
-Adobe-iTC Souvenir-Light-I-Normal- -10-100-75-75-P-59-ISO8859-1 
-Adobe-iTC Souvenir-Light-Il-Normal- -12-120-75-75-P-69-ISO8859-1 
~Adobe-ITC Souvenir-Light-!-Normal- -14-140-75-75-P-82-ISO8859-1 
~Adobe-ITC Souvenir-Light-!-Normal- -18-180-75-75-P-104-ISO8859-1 


-Adobe-ITC Souvenir-Light-l-Normal- -24-240-75-75-P-139-ISO8859-1 














SYMBOL 

SYMBOLS -Adobe-Symbol-Medium-R-Normal- -8-80-75-75-P-51-ADOBE-FONTSPECIFIC 
SYMBOL10 -Adobe-Symbol-Medium-R-Normal- -10-100-75-75-P-61-ADOBE-FONTSPECIFIC 
SYMBOL12 -Adobe-Symbol-Medium-R-Normal- -12-120-75-75-P-74-ADOBE-FONTSPECIFIC 
SYMBOL14 -ADOBE-Symbol-Medium-R-Normal- -14-140-75-75-P-85-ADOBE-FONTSPECIFIC 
SYMBOL18 -Adobe-Symbol-Medium-R-Normal- -18-180-75-75-P-107-ADOBE-FONTSPECIFIC 
SYMBOL24 -Adobe-Symbol-Medium-R-Normal- -24-240-75-75-P-142-ADOBE-FONTSPECIFIC 
TERMINAL 

TERMINAL14 -DEC-Terminal-Medium-R-Normal- -14-140-75-75-C-80-ISO8859-1 

TERMINAL18 -Bitstream-Terminal-Medium-R-Normal- -18-180-75-75-C-110-ISO8859-1 
TERMINAL28 -DEC-Terminal-Medium-R-Normal- -28-280-75-75-C-160-ISO8859-1 

TERMINAL36 


TERMINAL_BOLD14 

TERMINAL_BOLD18 

TERMINAL_BOLD28 

TERMINAL_BOLD36 
TERMINAL_BOLD_DBLWIDE14 
TERMINAL_BOLD_DBLWIDE18 
TERMINAL_BOLD_DBLWIDE_DECTECH14 
TERMINAL_BOLD_DBLWIDE_DECTECH18 
TERMINAL_BOLD_DECTECH14 
TERMINAL_BOLD_DECTECH18 
TERMINAL_BOLD_DECTECH28 


TERMINAL_BOLD_DECTECH36 


-Bitstream-Terminal-Medium-R-Normal- -36-360-75-75-C-220-ISO8859-1 
-DEC-Terminal-Bold-R-Normal- -14-140-75-75-C-80-ISO8859-1 
-Bitstream-Terminal-Bold-R-Normal- -18-180-75-75-C-110-ISO8859-1 
-DEC-Terminal-Bold-R-Normal- -28-280-75-75-C-160-ISO8859-1 
-Bitstream-Terminal-Bold-R-Normal- -36-360-75-75-C-220-ISO8859-1 
-DEC-Terminal-Bold-R-Double Wide- -14-140-75-75-C-160-ISO8859-1 
-Bitstream-Terminal-Bold-R-Double Wide- -18-180-75-75-C-220-ISO8859-1 
-DEC-Terminal-Bold-R-Double Wide- -14-140-75-75-C-160-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Double Wide- -18-180-75-75-C-220-DEC-DECtech 
-DEC-Terminal-Bold-R-Normal- -14-140-75-75-C-80-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Normal- -18-180-75-75-C-110-DEC-DECtech 
-DEC-Terminal-Bold-R-Normal- -28-280-75-75-C-160-DEC-DECtech 


-Bitstream-Terminal-Bold-R-Normal- -36-360-75-75-C-220-DEC-DECtech 
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Font Name . 





TERMINAL 





TERMINAL_BOLD_NARROW14 
TERMINAL_BOLD_NARROW18 
TERMINAL_BOLD_NARROW28 
TERMINAL_BOLD_NARROW36 
TERMINAL_BOLD_NARROW_DECTECH14 
TERMINAL_BOLD_NARROW_DECTECH18 
TERMINAL_BOLD_NARROW_DECTECH28 
TERMINAL_BOLD_NARROW_DECTECH36 
TERMINAL_BOLD_WIDE14 
TERMINAL_BOLD_WIDE18 
TERMINAL_BOLD_WIDE_DECTECH14 
TERMINAL_BOLD_WIDE_DECTECH18 
TERMINAL_DBLWIDE14 
TERMINAL_DBLWIDE18 
TERMINAL_DBLWIDE_DECTECH14 
TERMINAL_DBLWIDE_DECTECH18 
TERMINAL_DECTECH14 
TERMINAL_DECTECH18 
TERMINAL_DECTECH28 
TERMINAL_DECTECH36 
TERMINAL_NARROW14 
TERMINAL_NARROW18 
TERMINAL_NARROW28 
TERMINAL_NARROW36 
TERMINAL_NARROW_DECTECH14 
TERMINAL_NARROW_DECTECH18 
TERMINAL_NARROW_DECTECH28 
TERMINAL_NARROW_DECTECH36 
TERMINAL_WIDE14 

TERMINAL_WIDE18 
TERMINAL_WIDE_DECTECH14 


TERMINAL_WIDE_DECTECH18 


-DEC-Terminal-Bold-R-Narrow- -14-140-75-75-C-60-ISO8859-1 
-Bitstream-Terminal-Bold-R-Narrow- -18-180-75-75-C-70-ISO8859-1 
-DEC-Terminal-Bold-R-Narrow- -28-280-75-75-C-120-ISO8859-1 
-Bitstream-Terminal-Bold-R-Narrow- -36-360-75-75-C-1 40-ISO8859-1 
-~DEC-Terminal-Bold-R-Narrow- -14-140-75-75-C-60-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Narrow- -18-180-75-75-C-70-DEC-DECtech 
-DEC-Terminal-Bold-R-Narrow- -28-280-75-75-C-120-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Narrow- -36-360-75-75-C-140-DEC-DECtech 
-DEC-Terminal-Bold-R-Wide- -14-140-75-75-C-120-ISO8859-1 
-Bitstream-Terminal-Bold-R-Narrow- -18-180-75-75-C-140-ISO8859-1 
-DEC-Terminal-Bold-R-Wide- -14-140-75-75-C-120-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Narrow- -18-180-75-75-C-140-DEC-DECtech 
-DEC-Terminal-Medium-R-Double Wide- -14-140-75-75-C-160-ISO8859-1 
-Bitstream-Terminal-Medium-R-Double Wide- -18-180-75-75-C-220-ISO8859-1 
-DEC-Terminal-Medium-R-Double Wide- -14-140-75-75-C-160-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Double Wide- -18-180-75-75-C-220-DEC-DECtech 
-DEC-Terminal-Medium-R-Normal- -14-140-75-75-C-80-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Normal- -18-180-75-75-C-110-DEC-DECtech 
-DEC-Terminal-Medium-R-Normal- -28-280-75-75-C-1 60-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Normal- -36-360-75-75-C-220-DEC-DECtech 
-DEC-Terminal-Medium-R-Narrow- -14-140-75-75-C-60-ISO8859-1 
-Bitstream-Terminal-Medium-R-Narrow- -18-180-75-75-C-70-ISO8859-1 
-DEC-Terminal-Medium-R-Narrow- -28-280-75-75-C-120-ISO8859-1 
-Bitstream-Terminal-Medium-R-Natrow- -36-360-75-75-C-140-ISO8859-1 
-DEC-Terminal-Medium-R-Narrow- -14-140-75-75-C-60-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Narrow- -18-180-75-75-C-70-DEC-DECtech 
-DEC-Terminal-Medium-R-Narrow- -28-280-75-75-C-120-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Narrow- -36-360-75-75-C-140-DEC-DECtech 
-DEC-Terminal-Medium-R-Wide- -14-140-75-75-C-120-ISO8859-1 
-Bitstream-Terminal-Medium-R-Wide- -18-180-75-75-C-140-ISO8859-1 
-DEC-Terminal-Medium-R-Wide- -14-140-75-75-C-120-DEC-DECtech 


-Bitstream-Terminal-Medium-R-Wide- -18-180-75-75-C-140-DEC-DECtech 
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TIMES 
TIMES_BOLD8 -ADOBE-Times-Bold-R-Normal- -8-80-75-75-P-47-ISO8859-1 


TIMES_BOLD10 
TIMES_BOLD12 
TIMES_BOLD14 
TIMES_BOLD18 
TIMES_BOLD24 
TIMES_BOLDITALIC8 
TIMES_BOLDITALIC10 
TIMES_BOLDITALIC12 
TIMES_BOLDITALIC14 
TIMES_BOLDITALIC18 
TIMES_BOLDITALIC24 
TIMES_ITALIC8 
TIMES_ITALIC10 
TIMES_ITALIC12 
TIMES_{TALIC14 
TIMES_ITALIC18 
TIMES_ITALIC24 
TIMES_ROMAN8 
TIMES_ROMAN10 
TIMES_ROMAN12 
TIMES_ROMAN14 
TIMES_ROMAN18 


TIMES_ROMAN24 


-ADOBE-Times-Bold-R-Normal- -10-100-75-75-P-57-ISO8859-1 
-ADOBE-Times-Bold-R-Normal- -12-120-75-75-P-67-ISO8859-1 
-ADOBE-Times-Bold-R-Normal- -14-140-75-75-P-77-ISO8859-1 
-ADOBE-Times-Bold-R-Normal- -18-180-75-75-P-99-ISO8859-1 
-ADOBE-Times-Bold-R-Normal- -24-240-75-75-P-132-ISO8859-1 
-ADOBE-Times-Bold-I-Normal- -8-80-75-75-P-47-ISO8859-1 
-ADOBE-Times-Bold-I-Normal- -10-100-75-75-P-57-ISO8859-1 
-ADOBE-Times-Bold-I-Normal- -12-120-75-75-P-68-ISO8859-1 
-ADOBE-Times-Bold-I-Normal- -14-140-75-75-P-77-ISO8859-1 
-ADOBE-Times-Bold-I-Normal- -18-180-75-75-P-98-ISO8859-1 
-ADOBE-Times-Bold-I-Normal- -24-240-75-75-P-128-ISO8859-1 
-ADOBE-Times-Medium-I-Normal- -8-80-75-75-P-42-ISO8859-1 
-ADOBE-Times-Medium-I-Normal- -10-100-75-75-P-52-ISO8859-1 
-ADOBE-Times-Medium-I-Normal- -12-120-75-75-P-63-ISO8859-1 
-ADOBE-Times-Medium-!-Normal- -14-140-75-75-P-73-ISO8859-1 
-ADOBE-Times-Medium-I-Normal- -18-180-75-75-P-94-ISO8859-1 
-ADOBE-Times-Medium-!-Normal- -24-240-75-75-P-125-ISO8859-1 
-ADOBE-Times-Medium-R-Normal- -8-80-75-75-P-44-ISO8859-1 
-ADOBE-Times-Medium-R-Normal- -10-100-75-75-P-54-ISO8859-1 
-ADOBE-Times-Medium-R-Normal- -12-120-75-75-P-64-ISO8859-1 
-ADOBE-Times-Medium-R-Normal- -14-140-75-75-P-74-ISO8859-1 
-ADOBE-Times-Medium-R-Normal- -18-180-75-75-P-94-ISO8859-1 


-ADOBE-Times-Medium-R-Normal- -24-240-75-75-P-124-ISO8859-1 
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FIXED_100DPI Fixed 
CURSOR_100DPI Cursor 
DECW$CURSOR_100DPI DECW$CURSOR 
DECW$SESSION_100DPI DECWS$SESSION 
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File Name Font Name 

VARIABLE_100DP! Variable_100dpi 

AVANT GARDE 

AVANTGARDE_BOOK8_100DP! -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -11-80-100-100-P-59-ISO8859-1 
AVANTGARDE_BOOK10_100DPI -Adobe-iITC Avant Garde Gothic-Book-R-Normal- -14-100-100-100-P-80-ISO8859-1 
AVANTGARDE_BOOK12_100DPI -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -17-120-100-100-P-93-ISO8859-1 
AVANTGARDE_BOOK14_100DPI ; -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -20-140-100-100-P-104-ISO8859-1 
AVANTGARDE_BOOK18_100DPI -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -25-180-100-100-P-138-ISO8859-1 
AVANTGARDE_BOOK24_100DP! -Adobe-ITC Avant Garde Gothic-Book-R-Normal- -34-240-100-100-P-183-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE8_100DP! -Avant Garde Gothic-Book-O-Normal- -10-80-100-100-P-59-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE1 0_100DPI -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -14-100-100-100-P-81-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE12_100DP! -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -17-120-100-100-P-92-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE14_100DP! : . -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -20-140-100-100-P-103-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE1 8.100DPI | -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -25-180-100-100-P-138-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE24_100DPI -Adobe-ITC Avant Garde Gothic-Book-O-Normal- -34-240-100-100-P-184-ISO8859-1 
AVANTGARDE_DEMI8_100DPI -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -11-80-100-100-P-61-ISO8859-1 
AVANTGARDE_DEMI10_100DPI_ . -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -14-100-100-100-P-82-ISO8859-1 
AVANTGARDE_DEMI12_100DPI -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -17-120-100-100-P-93-ISO8859-1 
AVANTGARDE_DEMI!14_1 OoDPI -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -20-140-100-100-P-105-ISO8859-1 
AVANTGARDE_DEMI18_i00DPI -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -25-180-100-100-P-140-ISO8859-1 
AVANTGARDE_DEMI24_100DP! -Adobe-ITC Avant Garde Gothic-Demi-R-Normal- -34-240-100-100-P-182-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE8_100DPI -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -11-80-100-100-P-61-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE10_100DPI -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -14-100-100-100-P-82-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE12_100DPI -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -17-120-100-100-P-93-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE14_100DPI_ -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -20-140-100-100-P-103-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE18_100DP! , -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -25-180-100-100-P-139-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE24_100DPI -Adobe-ITC Avant Garde Gothic-Demi-O-Normal- -34-240-100-100-P-183-ISO8859-1 
COURIER 

COURIER8_100DPI -Adobe-Courier-Medium-R-Normal- -11-80-100-100-M-60-ISO8859-1 
COURIER10_100DP! -Adobe-Courier-Medium-R-Normal- -14-100-100-100-M-90-ISO8859-1 
COURIER12_100DPi -Adobe-Courier-Medium-R-Normal- -17-120-100-100-M-100-ISO8859-1 
COURIER14_100DPI -Adobe-Courier-Medium-R-Normal- -20-140-100-100-M-110-ISO8859-1 
COURIER18_100DPI . . -Adobe-Courier-Medium-R-Normal- -25-180-100-100-M-150-ISO8859-1 
COURIER24_100DPI -Adobe-Courier-Medium-R-Normal- -34-240-100-100-M-200-ISO8859-1 
COURIER_BOLD8_100DPI -Adobe-Courier-Bold-R-Normal- -11-80-100-100-M-60-ISO8859-1 
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COURIER 

COURIER_BOLD10_100DPI -Adobe-Courier-Bold-R-Normal- -14-100-100-100-M-90-ISO8859-1 
COURIER_BOLD12_100DP! -Adobe-Courier-Bold-R-Normal- -17-120-100-100-M-100-ISO8859-1 
COURIER_BOLD14_100DPI -Adobe-Courier-Bold-R-Normal- -20-140-100-100-M-110-ISO8859-1 
COURIER_BOLD18_100DP! -Adobe-Courier-Bold-R-Normal- -25-180-100-100-M-150-ISO8859-1 
COURIER_BOLD24_100DPI -Adobe-Courier-Bold-R-Normal- -34-240-100-100-M-200-ISO8859-1 
COURIER_BOLDOBLIQUE8_100DPI -Adobe-Courier-Bold-O-Normai- -11-80-100-100-M-60-ISO8859-1 
COURIER_BOLDOBLIQUE10_100DPI -Adobe-Courier-Bold-O-Normal- -14-100-100-100-M-90-ISO8859-1 
COURIER_BOLDOBLIQUE12_100DPI -Adobe-Courier-Bold-O-Normal- -17-120-100-100-M-100-ISO8859-1 
COURIER_BOLDOBLIQUE14_100DPI -Adobe-Courier-Bold-O-Normal- -20-140-100-100-M-110-ISO8859-1 
COURIER_BOLDOBLIQUE18_100DPI -Adobe-Courier-Bold-O-Normal- -25-180-100-100-M-150-ISO8859-1 
COURIER_BOLDOBLIQUE24_100DPI -Adobe-Courier-Bold-O-Normal- -34-240-100-100-M-200-ISO8859-1 
COURIER_OBLIQUE8_100DP! -Adobe-Courier-Medium-O-Normal- -11-80-100-100-M-60-ISO8859-1 
COURIER_OBLIQUE10_100DPI -Adobe-Courier-Medium-O-Normal- -14-100-100-100-M-90-ISO8859-1 
COURIER_OBLIQUE12_100DPI -Adobe-Courier-Medium-O-Normal- -17-120-100-100-M-100-ISO8859-1 
COURIER_OBLIQUE14_100DPI -Adobe-Courier-Medium-O-Normal- -20-140-100-100-M-110-ISO8859-1 
COURIER_OBLIQUE18_100DPI -Adobe-Courier-Medium-O-Normal- -25-180-100-100-M-150-ISO8859-1 
COURIER_OBLIQUE24_100DP! -Adobe-Courier-Medium-O-Normal- -34-240-100-100-M-200-ISO8859-1 
HELVETICA 

HELVETICA8_100DPI -Adobe-Helvetica-Medium-R-Normal- -11-80-100-100-P-56-ISO8859-1 
HELVETICA10_100DPI -Adobe-Helvetica-Medium-R-Normal- -14-100-100-100-P-76-ISO8859-1 
HELVETICA12_100DPI -Adobe-Helvetica-Medium-R-Normal- -17-120-100-100-P-88-ISO8859-1 
HELVETICA14_100DP! -Adobe-Helvetica- Medium-R-Normat -20-140-100-100-P-100-ISO8859-1 
HELVETICA18_100DPI -Adobe-Helvetica-Medium-R-Normal- -25-180-100-100-P-130-ISO8859-1 
HELVETICA24_100DPI -Adobe-Helvetica-Medium-R-Normal- -34-240-100-100-P-176-ISO8859-1 
HELVETICA_BOLD8_100DPI -Adobe-Helvetica-Bold-R-Normal- -11-80-100-100-P-60-ISO8859-1 
HELVETICA_BOLD10_100DPI -Adobe-Helvetica~Bold-R-Normal- -14-100-100-100-P-82-ISO8859-1 
HELVETICA_BOLD12_100DPI -Adobe-Helvetica-Bold-R-Normal- -17-120-100-100-P-92-ISO8859-1 
HELVETICA_BOLD14_100DP! -Adobe-Helvetica-Bold-R-Normal- -20-140-100-100-P-105-ISO8859-1 
HELVETICA_BOLD18_100DPI -Adobe-Helvetica-Boid-R-Normal- -25-180-100-100-P-138-ISO8859-1 
HELVETICA_BOLD24_100DPI -Adobe-Helvetica-Bold-R-Normal- -34-240-100-100-P-182-ISO8859-1 
HELVETICA_BOLDOBLIQUE8_100DPI -Adobe-Helvetica-Bold-O-Normal- -11-80-100-100-P-60-ISO8859-1 
HELVETICA_BOLDOBLIQUE10_100DP! -Adobe-Helvetica-Bold-O-Normal- -14-100-100-100-P-82-ISO8859-1 
HELVETICA_BOLDOBLIQUE12_100DPI -Adobe-Helvetica-Bold-O-Normal- -17-120-100-100-P-92-ISO8859-1 
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HELVETICA_BOLDOBLIQUE18_100DPI 
HELVETICA_BOLDOBLIQUE24_100DPI 


HELVETICA_OBLIQUE8_100DPI 

HELVETICA_OBLIQUE10_100DPI 
HELVETICA_OBLIQUE12_100DPI 
HELVETICA_OBLIQUE14_100DPI 
HELVETICA_OBLIQUE18_100DPI 


HELVETICA_OBLIQUE24_100DPI 


-Adobe-Helvetica-Bold-O-Normal- -25-180-100-100-P-138-ISO8859-1 
-Adobe-Helvetica-Bold-O-Normal- -34-240-100-100-P-182-ISO8859-1 
-Adobe-Helvetica-Medium-O-Normal- -11-80-100-100-P-57-ISO8859-1 
~Adobe-Helvetica-Medium-O-Normal- -14-100-100-100-P-78-ISO8859-1 
-Adobe-Helvetica-Medium-O-Normal- -17-120-100-100-P-88-ISO8859-1 
-Adobe-Helvetica-Medium-O-Normal- -20-140-100-100-P-98-ISO8859-1 
-Adobe-Helvetica-Medium-O-Normal- -25-180-100-100-P-130-ISO8859-1 


-Adobe-Helvetica-Medium-O-Normal- -34-240-100-100-P-176-ISO8859-1 





INTERIM 





INTERIM_DM_EXTENSION14_100DPI 


INTERIM_DM_ITALIC14_100DPI 


INTERIM_DM_SYMBOL14_100DPI 


-ADOBE-Interim DM-Medium-I-Normal- -20-140-100-100-P-180-DEC-DECMATH_EXTENSION 
-ADOBE-Interim DM-Medium-!-Normal- -20-140-100-100-P-180-DEC-DECMATH_ITALIC 


-ADOBE-Interim DM-Medium-I-Normal- -20-140-100-100-P-180-DEC-DECMATH_SYMBOL 





LUBALIN GRAPH 





LUBALINGRAPH_BOOK8_100DPI 

LUBALINGRAPH_BOOK10_100DPI 
LUBALINGRAPH_BOOK12_100DPI 
LUBALINGRAPH_BOOK14_100DPI 
LUBALINGRAPH_BOOK18_100DPI 


LUBALINGRAPH_BOOK24_100DPI 


-Adobe-ITC Lubalin Graph-Book-R-Normal- -11-80-100-100-P-60-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-R-Normal- -14-100-100-100-P-81-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-R-Normal- -17-120-100-100-P-89-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-R-Normal- -19-140-100-100-P-106-ISO8859-1 
-Adobe-iTC Lubalin Graph-Book-R-Normal- -24-180-100-100-P-139-ISO8859-1 


-Adobe-ITC Lubalin Graph-Book-R-Normal- -33-240-100-100-P-180-ISO8859-1 


LUBALINGRAPH_BOOKOBLIQUE8_100DP! -Adobe-ITC Lubalin Graph-Book-O-Normal- -11-80-100-100-P-60-ISO8859-1 


LUBALINGRAPH_BOOKOBLIQUE10_100DPI -Adobe-ITC Lubalin Graph-Book-O-Normal- -14-100-100-100-P-82-ISO8859-1 
LUBALINGRAPH_BOOKOBLIQUE12_100DPI -Adobe-ITC Lubalin Graph-Book-O-Normal- -19-120-100-100-P-89-ISO8859-1 
LUBALINGRAPH_BOOKOBLIQUE14_100DPI -Adobe-ITC Lubalin Graph-Book-O-Normal- -20-140-100-100-P-105-ISO8859-1 
LUBALINGRAPH_BOOKOBLIQUE18_100DPI -Adobe-ITC Lubalin Graph-Book-O-Normal- -24-180-100-100-P-1 40-ISO8859- 1 


LUBALINGRAPH_BOCKOBLIQUE24_100DPI -Adobe-!TC Lubalin Graph-Book-O-Normal- -33-240-100-100-P-181-ISO8859-1 


LUBALINGRAPH_DEMI8_100DPI 

LUBALINGRAPH_DEMI10_100DPI 
LUBALINGRAPH_DEMI12_100DPI 
LUBALINGRAPH_DEMI14_100DP! 
LUBALINGRAPH_DEMI18_100DPI 


LUBALINGRAPH_DEMI24_100DP! 


-Adobe-ITC Lubalin Graph-Demi-R-Normal- -11-80-100-100-P-61-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal- -14-100-100-100-P-85-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal- -17-120-100-100-P-92-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal- -19-140-100-100-P-109-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal- -24-180-100-100-P-144-ISO8859-1 


-Adobe-ITC Lubalin Graph-Demi-R-Normal- -33-240-100-100-P-184-ISO8859-1 
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LUBALINGRAPH_DEMIOBLIQUE10_100DPI -Adobe-ITC Lubalin Graph-Demi-O-Normal- -14-100-100-100-P-85-ISO8859-1 
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MENU10_100DP! 


MENU12_100DP! 


-Bigelow & Holmes-Menu-Medium-R-Normal- -14-100-100-100-P-77-ISO8859-1 


-Bigelow & Holmes-Menu-Medium-R-Normal- -17-120-100-100-P-92-ISO8859-1 





NEW CENTURY SCHOOLBOOK 





NEWCENTURYSCHLBK_BOLD8_7100DPI 

NEWCENTURYSCHLBK_BOLD10_100DP! 
NEWCENTURYSCHLBK_BOLD12_100DPI 
NEWCENTURYSCHLBK_BOLD14_100DPI 
NEWCENTURYSCHLBK_BOLD18_100DPI 


NEWCENTURYSCHLBK_BOLD24_100DPi 


-Adobe-New Century Schoolbook-Bold-R-Normal- -11-80-100-100-P-66-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal- -14-100-100-100-P-87-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal- -17-120-100-100-P-99-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal- -20-140-100-100-P-113-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal- -25-180-100-100-P-149-ISO8859-1 


-Adobe-New Century Schoolbook-Bold-R-Normal- -34-240-100-100-P-193-ISO8859-1 


NEWCENTURYSCHLBK_BOLDITALIC8_100DP! -Adobe-New Century Schoolbook-Bold-I-Normal- -11-80-100-100-P-66-ISO8859-1 


NEWCENTURYSCHLBK_BOLDITALIC10_100DPI -Adobe-New Century Schoolbook-Bold-I-Normal- -14-100-100-100-P-88-ISO8859-1 
NEWCENTURYSCHLBK_BOLDITALIC12_100DPI -Adobe-New Century Schoolbook-Bold-!-Normal- -17-120-100-100-P-99-ISO8859-1 
NEWCENTURYSCHLBK_BOLDITALIC14_100DPI -Adobe-New Century Schoolbook-Bold-I-Normal- -20-140-100-100-P-111-ISO8859-1 
NEWCENTURYSCHLBK_BOLDITALIC18_100DP! -Adobe-New Century Schoolbook-Bold-I-Normal- -25-180-100-100-P-148-ISO8859-1 


NEWCENTURYSCHLBK_BOLDITALIC24_100DP! -Adobe-New Century Schoolbook-Bold-I-Normal- -34-240-100-100-P-193-ISO8859-1 


NEWCENTURYSCHLBK_ITALIC8_100DPI 

NEWCENTURYSCHLBK_ITALIC10_100DPI 
NEWCENTURYSCHLBK_ITALIC12_100DPI 
NEWCENTURYSCHLBK_ITALIC14_100DP! 
NEWCENTURYSCHLBK_ITALIC18_100DPI 
NEWCENTURYSCHLBK_ITALIC24_100DPI 
NEWCENTURYSCHLBK_ROMANS8_100DPI 


-Adobe-New Century Schoolbook-Medium-!-Normal- -11-80-100-100-P-60-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-I-Normal- -14-100-100-100-P-81-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-l-Normal- -17-120-100-100-P-92-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-I-Normal- -20-140-100-100-P-104-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-!-Normal- -25-180-100-100-P-136-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-I-Normal- -34-240-100-100-P-182-ISO8859-1 
-Adobe-New Century Schoolbook-Medium-R-Normal- -11-80-100-100-P-60-ISO8859-1 


NEWCENTURYSCHLBK_ROMAN10_100DPI -Adobe-New Century Schoolbook-Medium-R-Normal- -14-100-100-100-P-82-ISO8859-1 


NEWCENTURYSCHLBK_ROMAN12_100DPI -Adobe-New Century Schoolbook-Medium-R-Normal- -17-120-100-100-P-91-ISO8859-1 





(continued on next page) 


D-12 


VMS DECwindows Fonts 


Table D-2 (Cont.) VMS DECwindows 100 DPI Fonts 




















File Name Font Name 

NEWCENTURYSCHLBK_ROMAN14_100DP! -Adobe-New Century Schoolbook-Medium-R-Normal- -20-140-100-100-P-103-ISO8859-1 
NEWCENTU RYSCHLBK_ROMAN18_100DPI -Adobe-New Century Schoolbook-Medium-R-Normal- -25-180-100-100-P-136-ISO8859-1 
NEWCENTURYSCHLBK_ROMAN24_100DPI -Adobe-New Century Schooibook-Medium-R-Normal- -34-240-100-100-P-181-ISO8859-1 
SOUVENIR 

SOUVENIR_DEMI8_100DPI -Adobe-ITC Souvenir-Demi-R-Normal- -11-80-100-100-P-62-ISO8859-1 
SOUVENIR_DEMI10_100DPI : -Adobe-iITC Souvenir-Demi-R-Normal- -14-100-100-100-P-90-ISO8859-1 
SOUVENIR_DEMI12_100DP! -Adobe-ITC Souvenir-Demi-R-Normal- -17-120-100-100-P-94-ISO8859-1 
SOUVENIR_DEMI14_100DP! -Adobe-ITC Souvenir-Demi-R-Normal- -20-140-100-100-P-112-ISO8859-1 
SOUVENIR_DEMI18_100DPI -Adobe-ITC Souvenir-Demi-R-Normal- -25-180-100-100-P-149-ISO8859-1 
SOUVENIR_DEMI24_100DP! -Adobe-ITC Souvenir-Demi-R-Normal- -34-240-100-100-P-191-ISO8859-1 
SOQUVENIR_DEMIITALIC8_1 OODP! -Adobe-ITC Souvenir-Demi-I-Normal- -11-80-100-100-P-67-ISO8859-1 
SOUVENIR_DEMIITALIC10_100DPI -Adobe-ITC Souvenir-Demi-I-Normal- -14-100-100-100-P-92-ISO8859-1 
SOUVENIR_DEMIITALIC12_100DPI : -Adobe-ITC Souvenir-Demi-l-Normal- -1 71 20-100-100-P-98-ISO8859-1 
SOUVENIR_DEMIITALIC14_1 OoDPI -Adobe-ITC Souvenir-Demi-I-Normal- -20-140-100-100-P-115-ISO8859-1 
SOUVENIR_DEMIITALIC18_100DPI , _ +Adobe-ITC Souvenir-Demi-l-Normal- -25-180-100-100-P-154-ISO8859-1 
SOUVENIR_DEMIITALIC24_1 OODPI -Adobe-ITC Souvenir-Demi-I-Normal- -34-240-100-100-P-197-ISO8859-1 
SOUVENIR_LIGHTS_100DPI -Adobe-ITC Souvenir-Light-R-Normal- -11-80-100-100-P-56-ISO8859-1 
SOUVENIR_LIGHT10_100DPI : -Adobe-ITC Souvenir-Light-R-Normal- -14-100-100-100-P-79-ISO8859-1 
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SOUVENIR_LIGHT18_100DPI -Adobe-ITC Souvenir-Light-R-Normal- -25-180-100-100-P-135-ISO8859-1 
SOUVENIR_LIGHT24_100DP! -Adobe-ITC Souvenir-Light-R-Normal- -34-240-100-100-P-174-ISO8859-1 
SOUVENIR_LIGHTITALIC8_100DP1 -Adobe-ITC Souvenir-Light-l-Normal- -11-80-100-100-P-59-ISO8859-1 
SOUVENIR_LIGHTITALIC10_100DPI -Adobe-ITC Souvenir-Light-I-Normal- -14-100-100-100-P-82-ISO8859-1 
SOUVENIR_LIGHTITALIC12_100DPI -Adobe-ITC Souvenir-Light-I-Normal- -17-120-100-100-P-88-ISO8859-1 
SOUVENIR_LIGHTITALIC14_100DP! . -Adobe-ITC Souvenir-Light-I-Normal- -20-140-100-100-P-104-ISO8859-1 
SOUVENIF_LIGHTITALIC18_100DPI -Adobe-ITC Souvenir-Light-l-Normal- -25-180-100-100-P-139-ISO8859-1 
SOUVENIR_LIGHTITALIC24_100DPI -Adobe-ITC Souvenir-Light-I-Normal- -34-240-100-100-P-177-ISO8859-1 
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SYMBOL18_100DPi -Adobe-Symbol-Medium-R-Normal- -25-180-100-100-P-142-ADOBE-FONTSPECIFIC. 
SYMBOL24_100DPI -Adobe-Symbol-Medium-R-Normal- -34-240-100-100-P-191-ADOBE-FONTSPECIFIC 
TERMINAL 

TERMINAL10_100DPI -DEC-Terminal-Medium-R-Normal- -14-100-100-100-C-80-ISO8859-1 
TERMINAL14_100DPI : -Bitstream-Terminal-Medium-R-Normal- -20-140-100-100-C-110-ISO8859-1 
TERMINAL20_100DPI ; -DEC-Terminal-Medium-R-Normal- -28-200-100-100-C-160-ISO8859-1 
TERMINAL28_100DPI -Bitstream-Terminal-Medium-R-Normal- -40-280-100-100-C-220-ISO8859-1 
TERMINAL_BOLD10_100DP! -DEC-Terminal-Bold-R-Normal- -14-100-100-100-C-80-ISO8859-1 
TERMINAL_BOLD14_100DPI -Bitstream-Terminal-Bold-R-Normal- -20-140-100-100-C-110-ISO8859-1 
TERMINAL, BOLD20_100DPI -DEC-Terminal-Bold-R-Normal- -28-200-100-100-C-160-ISO8859-1 
TERMINAL_BOLD28_100DPI . -Bitstream-Terminal-Bold-R-Normal- -40-280-100-100-C-220-ISO8859-1 
TERMINAL_BOLD_DBLWIDE10_100DPI -DEC-Terminal-Bold-R-Double Wide- -14-100-100-100-C-160-ISO8859-1 
TERMINAL_BOLD_DBLWIDE14_100DP! -Bitstream-Terminal-Bold-R-Double Wide- -20-140-100-100-C-220-ISO8859-1 
TERMINAL_BOLD_DBLWIDE_DECTECH10_100DPi -DEC-Terminal-Bold-R-Double Wide- -14-100-100-100-C-160-DEC-DECtech 
TERMINAL_BOLD_DBLWIDE_DECTECH14_100DPI -Bitstream-Terminal-Bold-R-Double Wide- -20-140-100-100-C-220-DEC-DECtech 
TERMINAL_BOLD..DECTECH10_100DPI -DEC-Terminal-Bold-R-Normal- -14-100-100-100-C-80-DEC-DECtech 
TERMINAL_BOLD_DECTECH14_100DPI -Bitstream-Terminal-Bold-R-Normal- -20-140-100-100-C-110-DEC-DECtech 
TERMINAL_BOLD_DECTECH20_100DPI -DEC-Terminal-Bold-R-Normal- -28-200-100-100-C-160-DEC-DECtech 
TERMINAL_BOLD_DECTECH28_100DPI -Bitstream-Terminal-Bold-R-Normal- -40-280-100-100-C-220-DEC-DECtech 
TERMINAL_BOLD_NARROW10_100DP! -DEC-Terminal-Boid-R-Narrow- -14-100-100-100-C-60-ISO8859-1 
TERMINAL_BOLD_NARROW14_100DP! -Bitstream-Terminal-Bold-R-Narrow- -20-140-100-100-C-70-ISO8859-1 
TERMINAL_BOLD_NARROW20_100DPI -DEC-Terminal-Bold-R-Narrow- -28-200-100-100-C-120-ISO8859-1 
TERMINAL_BOLD_NARROW28_100DP! -Bitstream-Terminal-Bold-R-Narrow- -40-280-100-100-C-140-ISO8859-1 
TERMINAL_BOLD_NARROW_DECTECH10_100DPI -DEC-Terminal-Bold-R-Narrow- -14-100-100-100-C-60-DEC-DECtech 
TERMINAL_BOLD_NARROW_DECTECH14_100DP! -Bitstream-Terminal-Bold-R-Narrow- -20-140-100-100-C-70-DEC-DECtech 
TERMINAL_BOLD_NARROW_DECTECH20_100DP! -DEC-Terminal-Bold-R-Narrow- -28-200-100-100-C-120-DEC-DECtech 
TERMINAL_BOLD_NARROW_DECTECH28_100DPi -Bitstream-Terminal-Bold-R-Narrow- -40-280-100-100-C-140-DEC-DECtech 
TERMINAL_BOLD_WIDE10_100DPI -DEC-Terminal-Bold-R-Wide- -14-100-100-100-C-120-ISO8859-1 
TERMINAL_BOLD_WIDE14_100DPI -Bitstream-Terminal-Bold-R-Narrow- -20-140-100-100-C-140-ISO8859-1 
TERMINAL_BOLD_WIDE_DECTECH10_100DPI -DEC-Terminal-Bold-R-Wide- -14-100-100-100-C-120-DEC-DECtech 
TERMINAL_BOLD_WIDE_DECTECH14_100DPI -Bitstream-Terminal-Bold-R-Narrow- -20-140-100-100-C-140-DEC-DECtech 
TERMINAL_DBLWIDE10_100DPI -DEC-Terminal-Medium-R-Double Wide- -14-100-100-100-C-160-ISO8859-1 
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TERMINAL_DBLWIDE_DECTECH10_100DPi -DEC-Terminal-Medium-R-Double Wide- -14-100-100-100-C-160-DEC-DECtech 
TERMINAL_DBLWIDE_DECTECH14_100DPI -Bitstream-Terminal-Medium-R-Double Wide- -20-140-100-100-C-220-DEC-DECtech 
TERMINAL,_DECTECH10_100DP! -DEC-Terminal-Medium-R-Normal- -14-100-100-100-C-80-DEC-DECtech 
TERMINAL_DECTECH14_100DPI -Bitstream-Terminal-Medium-R-Normal- -20-140-100-100-C-110-DEC-DECtech 
TERMINAL_DECTECH20_100DP! -DEC-Terminal-Medium-R-Normal- -28-200-100-100-C-160-DEC-DECtech 
TERMINAL_DECTECH28_100DPI -Bitstream-Terminal-Medium-R-Normal- -40-280-100-100-C-220-DEC-DECtech 
TERMINAL_NARROW10_100DPI -DEC-Terminal-Medium-R-Narrow- -14-100-100-100-C-60-ISO8859-1 
TERMINAL_NARROW14_100DPI -Bitstream-Terminal-Medium-R-Narrow- -20-140-100-100-C-70-ISO8859-1 
TERMINAL_NARROW20_100DPI -DEC-Terminal-Medium-R-Narrow- -28-200-1 00-1 00-C-120-iSO8859-1 
TERMINAL_NARROW28_100DPI -Bitstream-Terminal-Medium-R-Narrow- -40-280-100-100-C-140-ISO8859-1 
TERMINAL_NARROW_DECTECH10_100DPI -DEC-Terminal-Medium-R-Narrow- -14-100-100-100-C-60-DEC-DECtech 
TERMINAL_NARROW_DECTECH14_100DPI -Bitstream-Terminal-Medium-R-Narrow- -20-140-100-100-C-70-DEC-DECtech 
TERMINAL_NARROW_DECTECH20_100DPI -DEC-Terminal-Medium-R-Narrow- -28-200-100-100-C-120-DEC-DECtech 
TERMINAL_NARROW_DECTECH28_i00DPI -Bitstream-Terminal-Medium-R-Narrow- -40-280-100-100-C-140-DEC-DECtech 
TERMINAL_WIDE10_100DPI : -DEC-Terminal-Medium-R-Wide- -14-100-100-100-C-120-ISO8859-1 
TERMINAL_WIDE14_100DP! ' -Bitstream-Terminal-Medium-R-Wide- -20-140-100-100-C-140-ISO8859-1 
TERMINAL_WIDE_DECTECH10_100DPi -DEC-Terminal-Medium-R-Wide- -14-100-100-100-C-120-DEC-DECtech 
TERMINAL_WIDE_DECTECH14_100DPI -Bitstream-Terminal-Medium-R-Wide- -20-140-100-100-C-140-DEC-DECtech 
TIMES 

TIMES_BOLD8_100DPI -Adobe-Times-Bold-R-Normal- -11-80-100-100-P-57-ISO8859-1 
TIMES_BOLD10_100DPI -Adobe-Times-Bold-R-Normal- -14-100-100-100-P-76-ISO8859-1 
TIMES_BOLD12_100DP! -Adobe-Times-Bold-R-Normal- -17-120-100-100-P-88-ISO8859-1 
TIMES_BOLD14_100DPI -Adobe-Times-Bold-R-Normal- -20-140-100-100-P-100-ISO8859-1 
TIMES_BOLD18_100DP! -Adobe-Times-Bold-R-Normal- -25-180-100-100-P-132-ISO8859-1 
TIMES_BOLD24_100DP! -Adobe-Times-Bold-R-Normal- -34-240-100-100-P-177-ISO8859-1 
TIMES_BOLDITALIC8_100DP! -Adobe-Times-Bold-I-Normal- -11-80-100-100-P-57-ISO8859-1 
TIMES_BOLDITALIC10_100DPI -Adobe-Times-Bold-I-Normal- -14-100-100-100-P-77-ISO8859-1 
TIMES_BOLDITALIC12_100DP! -Adobe-Times-Bold-!-Normal- -17-120-100-100-P-86-ISO8859-1 
TIMES_BOLDITALIC14_100DPI -Adobe-Times-Bold-I-Normal- -20-140-100-100-P-98-ISO8859-1 
TIMES_BOLDITALIC18_100DPI -Adobe-Times-Bold-Il-Normal- 25-1 80-100-100-P-128-ISO8859-1 
TIMES_BOLDITALIC24_100DPI -Adobe-Times-Bold-I-Normal- -34-240-100-100-P-170-ISO8859-1 
TIMES_ITALIC8_100DPI -Adobe-Times-Medium-l-Normal- -11-80-100-100-P-52-ISO8859-1 
TIMES_ITALIC10_100DP! -Adobe-Times-Medium-!-Normal- -14-100-100-100-P-73-ISO8859-1 
TIMES_ITALIC12_100DPi -Adobe-Times-Medium-I-Normal- -17-120-100-100-P-84-ISO8859-1 





(continued on next page) 


D-15 


VMS DECwindows Fonts 


Table D-2 (Cont.) VMS DECwindows 100 DPI Fonts 











File Name Font Name 

TIMES 

TIMES_ITALIC14_100DPI -Adobe-Times-Medium-I-Normal- -20-140-100-100-P-94-ISO8859-1 
TIMES_ITALIC18_100DP1 -Adobe-Times-Medium-I-Normal- -25-180-100-100-P-125-ISO8859-1 
TIMES_ITALIC24_100DPI -Adobe-Times-Medium-|-Normal- -34-240-100-100-P-168-ISO8859-1 
TIMES_ROMANS8_100DPI . -Adobe-Times-Medium-R-Normal- -11-80-100-100-P-54-ISO8859-1 
TIMES_ROMAN10_100DPI -Adobe-Times-Medium-R-Normal- -14-100-100-100-P-74-ISO8859-1 
TIMES_ROMAN12_100DPI -Adobe-Times-Medium-R-Normal- -17-120-100-100-P-84-ISO8859-1 
TIMES_ROMAN14_100DPI -Adobe-Times-Medium-R-Normal- -20-140-100-100-P-96-ISO8859-1 
TIMES_ROMAN18_100DP! -Adobe-Times-Medium-R-Normal- -25-180-100-100-P-125-ISO8859-1 


TIMES_ROMAN24_100DP! -Adobe-Times-Medium-R-Normal- -34-240-100-100-P-170-ISO8859-1 
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A 


ALLOC COLOR CELLS routine «5-16 
ALLOC COLOR routine » 5-12 
ALLOC NAMED COLOR routine « 5-10 
Any event data structure * 9-3 
Arc 
drawing *6—14 to 6-15 
drawing more than one * 6-15 
filling * 6-18 
GC members used to draw » 6-16 
GC members used to fill * 6-19 
styles of filling * 4-9 
illustrated * 4-14 
Arc data structure + 6-15 
Area 
clearing * 6-22 
copying * 6-22 
filling * 6-18 
GC members used to copy * 6-24 
Atom 
associated with font properties * 8—11 
associated with window properties * 3-18 
definition » 3-17 
Attribute 
changing window * 3-39 to 3-41 
defining window « 3-7 
getting information about window * 3-42 to 3-44 


Background. color 

specifying * 4—4 
Backing pixel 

definition * 3-11 

effect of changing * 3-41 
Backing plane 

definition * 3-11 

effect of changing * 3—41 
Backing store 

definition * 3-11 

effect of changing * 3-41 
BDF (Bitmap Distribution Format) * A—1 





Bit gravity 

definition * 3—11 

effect of changing * 3-41 
Bitmap 

creating data file for » 7-4 
Bitmap Distribution Format 

See BDF 
Blocking 

definition * 9-56 
Bounding box 

line * 4—10 

text character * 8—1 
Button 

handling presses and releases «9-8 to 9-11 
Button event data structure + 9-9 


C 


CHANGE WINDOW ATTRIBUTES routine « 3—40 
Char 2B data structure * 8-6 
CHECK IF EVENT routine « 9-58 
CHECK MASK EVENT routine * 9-59 
CHECK TYPED EVENT routine « 9-59 
CHECK TYPED WINDOW EVENT routine * 9-59 
CHECK WINDOW EVENT routine + 9-58 
Child window 

See also Window hierarchy 

definition * 1-3 

getting information about * 3-41 
Circulate event data structure * 9-37 
CIRCULATE SUBWINDOWS DOWN routine « 3-39 
CIRCULATE SUBWINDOWS UP routine * 3-39 
CLEAR AREA routine « 6-23 
CLEAR WINDOW routine « 6-23 
Client 

communication with * 9-50 to 9-56 

connecting with server « 2-3 

definition * 1-1 

sending message to «9-50 
Client message event data structure * 9-50 
Client request 

controlling * 2-8 

handling by Xlib 

See Server 
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Index 


Client-server connection 
breaking * 2-4 
establishing * 2-3 
getting information about » 2-5 
Clipping 
specifying pixmap for » 4-10 
CLOSE DISPLAY routine » 2-4 
Color 
allocating for exclusive use * 5—16 
direct color + 5-6 
exclusive use of *5~—14 to 5-25 
freeing storage assigned for * 5~25 
gray scale « 5—5 
index * 5~2 
named 
list of « C—1 
pseudocolor * 5—5 
range of «5-2 
RGB components « 5-2 
RGB values * 5-5 
screen configuration and « 5-5 
sharing» 5-10 to 5-14 
named «5-10 to 5-12 
specifying exact value *5-12 to 5-14 
static color * 5-6 
static gray «5-6 
true color « 5-6 
type of 


See Visual type 
using named « 5-10 
Color cell 
allocating for exclusive use «5-15 to 5-25 
definition » 5-2 
Color data structure * 5-12 
Color index 
definition » 5~2 
Color map * 5-1 to 5-4 
creating * 5-15 
creating from default « 5-24 
default 
allocating for exclusive use * 5-14 
definition « 5-2 
focus *« 5—4 
hardware * 5-4 
installing * 5-4 
receiving notification of change in » 9-49 
specifying * 5—15 
specifying for a window * 3-12 
storing colors * 5-25 
virtual * 5—4 
Color map event data structure » 9-49 


index—2 


Color values 
specifying exact * 5-12 
Configure event data structure * 9-38 
Configure request 
overriding » 3-12 
CONFIGURE WINDOW routine « 3-31 
Confirming resource creation * 9-62 
CONVERT SELECTION routine * 3-31 
COPY AREA routine » 6-24 
COPY COLORMAP AND FREE routine « 5-24 
COPY PLANE routine * 6-24 
CREATE COLORMAP routine * 5-15 
CREATE FONT CURSOR routine * 6-33 
CREATE GLYPH CURSOR routine + 6-33 
CREATE IMAGE routine + 7-8 
CREATE PIXMAP CURSOR routine » 6-37 
CREATE PIXMAP routine « 7-1 
CREATE REGION routine » 6-24 
CREATE SIMPLE WINDOW routine » 3-6 
Create window event data structure » 9-40 
CREATE WINDOW routine * 3-7 
Crossing event data structure * 9-16 
Cursor 
creating *6-32 to 6-38 
using a client cursor font « 6-34 
using pixmaps * 6-37 
using VMS DECwindows cursor font » 6-33 
using Xlib cursor font » 6-32 
definition * 6-32 
destroying * 6-39 
determining size of * 6-37 
effect of changing default » 3-41 
elements of * 6-34 
illustration of shape and mask * 6-35 
making visible on screen * 6—33 
mask ¢ 6—35 
shape ¢ 6-35 
specifying for a window ¢ 3-12 


D 


Debugging programs « 1-9 
DEFAULT COLORMAP routine * 5-15 
DEFAULT VISUAL OF SCREEN routine * 5-8 
Default window characteristics 

See Window 
DEFINE CURSOR routine * 6-33 
Depth 

definition » 5-2 





DESTROY SUBWINDOWS routine » 3-16 
Destroy window event data structure » 9-41 
DESTROY WINDOWS routine »* 3-16 
Device type 
See Visual type 
Direct color * 5-6 
Display 
closing * 2-4 
compared to hardware « 2—1 
information routines «2-5 to 2—7 
opening * 2-3 
server response to closing * 2-4 to 2-5 
Display information routines *2—5 to 2-7 
DISPLAY NAME routine * 9-62 
Display type 
See Visual type 
DRAW ARC routine « 6-13 
DRAW ARCS routine * 6-16 
DRAW IMAGE STRING 16 routine * 8-23 
DRAW IMAGE STRING routine » 8-23 
DRAW LINE routine * 6-5 
DRAW LINES routine ¢ 6-6 
DRAW POINT routine * 6-2 
DRAW RECTANGLE routine * 6-9 
DRAW SEGMENTS routine « 6-9 
DRAW STRING 16 routine * 8-21 
DRAW STRING routine * 8-21 
DRAW TEXT 16 routine » 8-20 
DRAW TEXT routine * 8-20 


E 


Error 
codes « 9-61 
handling event « 9-59 
using default * 9-60 
Error event data structure * 9-60 
Error handling conditions * 1-9 
Error reporting 
delays caused by Xlib buffering * 1-9 
Event 
blocking * 9-56 
button press and release «9-8 to 9-11 
client communication * 9-50 to 9-56 
client message « 9-50 
color map * 9-49 
convert selection « 9—54 
data structure used to report all types of * 9~3 





index 


Event (Cont.) 
data structure used to report multiple 
types of + 9-4 
default error handlers * 9-59 
definition * 9-1 
error codes * 9-61 
error handling «9-59 to 9-62 
graphics exposure * 9-30 to 9-35 
handling queue * 9-56 to 9-59 
key 9-14 
keyboard mapping * 9-44 
key mapping * 9-44 
masks used to specify »* 9-5 
notifying ancestors of «3-12 
pointer * 9-8 
pointer grab « 9-22 
pointer mapping « 9-44 
pointer motion « 9-11 
predicate procedure 
definition * 9-57 
processing * 9-1 to 9-4 
property change « 9-51. 
reported as result of window entry or exit 9-18 
selecting 
using a mask «9-58 to 9-59 
using predicate procedure »* 9-57 
using the SELECT INPUT routine * 9-5 
when changing window attributes « 9-7 
when creating a window * 9-7 
selecting types of *9-5 to 9-8 
selection notification * 9-55 
selection ownership * 9-53 
sending to other applications « 9-59 
specifying type associated with a window « 3-12 
types * 9-2 
types always reported « 9-5 
window circulation * 9-37 
window creation * 9-40 
window destruction * 9-41 
window entry or exit 
caused by a grab + 9-18 
caused by pointer movement + 9-18 
window exposure «9-28 to 9-30 
window gravity * 9-42 
window mapping * 9-43 
window reparenting * 9-45 
window unmapping * 9-47 
window visibility * 9-48 
Event data structure » 9-4 
Event mask 
effect of changing «3-41 
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Index 


Event mask (Cont.) 
selecting events out of order using * 9-58 
Event queue*9-56 
checking * 9-57 
putting event back on «9-59 
returning next event * 9-57 
EVENTS QUEUED routine * 9-57 
Exposure 
notification of window region * 4-10 


F 


FILL POLYGON routine » 6-20 
Fill style * 4—8 
illustration of » 4-13 
Flags 
for defining color values * 5—1 
for referring to window attributes * 3-13 
for referring to window change values « 3-33 
Focus change event data structure » 9~22 
Font 
advantages of minimum bounding box « A-1 
associating with graphics context « 8-15 
bounding box of « 8-8 
compiling » A—1 
complimentary routines * 8—17 
converting from BDF to SNF « A-1 
definition * 8—4 
fixed * 8-4 
freeing resources * 8—17 
getting illustration of when compiling * A~1 
getting information about * 8-15 
getting information about a property * 8-15 
list of VMS DECwindows « D-1 
loading * 8-14 
monospaced « 8—4 
multiple-row * 8-5 
naming 
conventions when « 8-13 
wildcards used when ¢ 8-14 
pixel size of * 8-14 
_ point size of «8-14 
properties ¢ 8-15 
single-row * 8-4 
specifying * 4-10, 8-13 
specifying output file * A—1 
Font prop data structure * 8-12 
Font struc data structure » 8-6 
Foreground color 
specifying » 4—4 
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FREE COLORMAP routine * 5-25 
FREE COLORS routine » 5-25 
FREE CURSOR routine « 6-39 
FREE PIXMAP routine * 7—3 


G 


GC 
See Graphics context 
GC data structure 
default values of * 4—1 
GC values data structure » 4—4 
flags for referring to members of ¢ 4-15 
illustrated * 4-3 
GET ERROR DATABASE TEXT routine * 9-62 
GET ERROR TEXT routine « 9-62 
GET GEOMETRY routine * 3-42 
GET IMAGE routine « 7-8 
GET SELECTION OWNER routine « 3-31 
GET VISUAL INFO routine * 5-9 
GET WINDOW ATTRIBUTES routine * 3-42 to 3-44 
Grab 
active * 9-8 
effect on input focus * 9-27 
handling pointer * 9-22 
passive * 9-8 
Graphics 
clearing areas *6~22 to 6-23 
' copying areas * 6-24 
defining characteristics of *4—2 to 4-20 
defining the position of » 6—1 
drawing 
arcs ¢ 6-13 
lines*6—5 to 6-9 
points * 6-2 to 6-5 
rectangles * 6—9 
filling areas *6-18 to 6-22 
introduction to * 6—1 
position relative to drawable « 6-1 
styles of filling * 4—8 
Graphics characteristics 
See Graphics context 
Graphics context 
changing * 4—21 
copying * 4—21 
default values of « 4—1 
defining in one call « 4-2 
definition » 4—1 
effect of window changes on * 4—21 





Graphics context (Cont.) 
maximum number of * 4-22 
overview of * 4-1 
specifying individual components of « 4—17 
using efficiently * 4-21 
Graphics expose event data structure * 9-31 
Graphics exposure «9-30 to 9-35 
definition * 9-30 
example of handling * 9-33 
Gravity event data structure * 9-42 
Gray scale + 5-5 


H 


Host machine 
specifying * 2-3 


IF EVENT routine + 9-58 
Image 

changing * 7-10 

creating * 7-8 

from pixmap * 7-8 

creating data file of » 7—4 

destroying * 7-11 

format of «7-9 

storing * 7-9 

transferring to drawable * 7~9 
Image data structure * 7-5 
Inferior window 

definition + 1-3 
Information routines 

as arguments to routines * 2-5 
Input focus 

change caused by grab * 9~27 

definition » 9-22 . 

normal keyboard * 9-24 
INSTALL COLORMAP routine » 5-4 


K 


Key 
mapping events * 9-44 
presses ° 9-14 
releases «9-14 

















index 


Keyboard input 
providing window manager hints about * 3-25 
Key event data structure * 9-14 
Key map 
changes in state of * 9-27 
Keymap event data structure * 9-27 


L 


Line 
dash offset illustrated * 4—15 
double dash * 4-6 
drawing more than one « 6-6 
endpoints of » 4-6 
how server draws ¢ 4-5 
on off dash * 4-6 
solid * 4-6 
specifying beginning of dashed « 4—10 
specifying length of dash in dashed « 4—10 
specifying style of » 4-6 
specifying width of *4—5 
styles of * 4—11 
styles of endpoints * 4-11 
styles of filling dashed * 4—8 
styles of joining another * 4-12 
styles of joining another line * 4—7 
treatment of coincident endpoints of « 4-6 
Xlib performance and width of « 4-5 
LIST FONTS routine « 8-15 
LIST FONTS WITH INFO routine » 8-15 
LOAD FONT routine * 8-14 
LOAD QUERY FONT routine » 8-14 
LOOKUP COLOR routine « 5-26 
LOWER WINDOW routine + 3-39 


Map event data structure * 9-43 
Mapping and unmapping windows «3-16 to 3—17 
Mapping event data structure « 9-44 
MAP RAISED routine « 3-16 
Map request 

overriding *3-12 . 
MAP SUBWINDOWS routine * 3-16 
MAP WINDOW routine » 3-16 
MASK EVENT routine « 9-58 
MATCH VISUAL INFO routine * 5-10 
Motion event data structure «9-11 
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MOVE RESIZE WINDOW routine « 3-36 
MOVE WINDOW routine * 3-36 


N 


Named VMS DECwindows colors 
list of * C—1 
using * 5-10 to 5-12. 
NEXT EVENT routine * 9-57 
NEXT REQUEST routine * 9-63 
No expose event data structure * 9-32 


O 


OPEN DISPLAY routine + 2-3 
Origin 

definition » 3-4 
Ownership 

See Window selection | 


p 


Parent window 
See also Window hierarchy 
definition » 3-2 
getting information about « 3-41 
receiving notification of change of » 9-45 
using attributes of * 3-6 
PEEK EVENT routine « 9-57 
PEEK IF EVENT routine » 9-58 
PENDING routine « 9-57 
Pixel 
and color values « 5—1 
definition » 3-4 
determining if inside a filled polygon + 4—9 
illustrated * 4-14 
relationship to planes »* 5-2 
Pixel value 
computing * 4—4 
Pixmap 
checking the creation of * 7-3 
clearing areas of * 6-22 
copying areas of » 6-24 
creating * 7-1 
creating from bitmap data file * 7-4 
example of creating * 7—1 
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Pixmap (Cont.) 
freeing storage for * 7-3 
Plane 
definition * 5—1 
Point 
determining location of * 6-3 
drawing more than one * 6-2 
GC members used to draw * 6-3 
Point data structure * 6-2 
Pointer 
button event handling «9-8 to 9-11 
mapping events * 9-44 
motion event handling «9-11 to 9-14 
Polygon 
filling 6-19 to 6-22 
GC members used to fill » 6-20 
POLYGON REGION routine * 6-24 
Predicate procedure * 9-58 
Property 
communicating with window manager using * 3-24 
defining for window manager « 3-25 
defining individual * 3-27 
definition * 3-17 
example of using * 3-21 
exchanging between clients » 3-30 
font «8-15 
receiving notification of change in « 9-51 
used by window manager ¢ 3-24 
Property event data structure * 9-52 
Protocol requests * B—1 
Pseudocolor * 5-5 
Pseudomotion 
definition « 9-16 
window entry or exit * 9-21 
PUT BACK EVENT routine « 9-59 
PUT IMAGE routine » 7-9 


Q 


QUERY BEST CURSOR routine » 6-37 
QUERY BEST SIZE routine » 4~9 

QUERY COLOR routine * 5-26 

QUERY POINTER routine « 3-42 

QUERY TEXT EXTENTS 16 routine * 8-18 
QUERY TEXT EXTENTS routine + 8-18 
QUERY TREE routine « 3-42 








R 


RAISE WINDOW routine « 3-39 
Rectangle 
drawing more than one « 6-10 
filling » 6-18 . 
GC members used to draw « 6-11 
GC members used to fill » 6-19 
Rectangle data structure * 6—11 
Region 
creating «6-24 to 6-27 
definition * 6-24 
example of intersecting » 6-28 
managing * 6-27 to 6-31 
Reparent event data structure * 9-45 
Request 
buffering * 1-9 
client « 1-9 
how Xlib handles client + 1-9 
RESIZE WINDOW routine + 3-36 
RESTACK WINDOW routine + 3-39 
Root window « 3-2 
definition * 1-3 
Routines 
ALLOC COLOR « 5—12 
ALLOC COLOR CELLS « 5-16 
ALLOC NAMED COLOR «5-10 
CHANGE WINDOW ATTRIBUTES « 3-40 
CHECK IF EVENT + 9-58 
CHECK MASK EVENT « 9-59 
CHECK TYPED EVENT « 9-59 
CHECK TYPED WINDOW EVENT « 9-59 
CHECK WINDOW EVENT « 9-58 
CIRCULATE SUBWINDOWS DOWN «3-39 
CIRCULATE SUBWINDOWS UP « 3-39 
CLEAR AREA «6-23 — 
CLEAR WINDOW « 6-23 
CLOSE DISPLAY « 2-4 
CONFIGURE WINDOW « 3-31 
CONVERT SELECTION « 3-31 
COPY AREA « 6-24 
COPY COLORMAP AND FREE « 5-24 
COPY PLANE « 6-24 
CREATE COLORMAP « 5-15 
CREATE FONT CURSOR ¢ 6-33 
CREATE GLYPH CURSOR * 6-33 
CREATE IMAGE « 7-8 
CREATE PIXMAP « 7-1 
CREATE PIXMAP CURSOR « 6-37 
CREATE REGION « 6-24 
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Routines (Cont.) 
CREATE SIMPLE WINDOW « 3-6 
CREATE WINDOW « 3-7 
DEFAULT COLORMAP « 5—15 
DEFAULT VISUAL OF SCREEN « 5-8 
DEFINE CURSOR « 6-33 
DESTROY SUBWINDOWS « 3-16 
DISPLAY NAME « 9-62 
DRAW ARC «6-13 
DRAW ARCS « 6-16 
DRAW IMAGE STRING « 8-23 
DRAW IMAGE STRING 16 « 8-23 
DRAW LINE «6-5 
DRAW LINES «6-6 
DRAW POINT «6-2 
DRAW RECTANGLE « 6-9 
DRAW SEGMENTS «6-9 
DRAW STRING ¢ 8-21 
DRAW STRING 16 « 8-21 
DRAW TEXT * 8-20 
DRAW TEXT 16° 8-20 
EVENTS QUEUED « 9-57 
FILL POLYGON « 6-20 
FREE COLORMAP « 5-25 
FREE COLORS « 5-25 
FREE CURSOR « 6-39 
FREE PIXMAP «7-3 
GET ERROR DATABASE TEXT « 9-62 
GET ERROR TEXT « 9-62 
GET GEOMETRY * 3-42 
GET IMAGE « 7-8 
GET SELECTION OWNER « 3-31 
GET VISUAL INFO « 5-9 
GET WINDOW ATTRIBUTES « 3-42 to 3-44 
IF EVENT ¢ 9-58 
INSTALL COLORMAP « 5-4 
LIST FONTS « 8-15 
LIST FONTS WITH INFO «8-15 
LOAD FONT « 8-14 
LOAD QUERY FONT «8-14 
LOOKUP COLOR « 5-26 
LOWER WINDOW -« 3-39 
MAP RAISED « 3-16 
MAP SUBWINDOWS « 3-16 
MAP WINDOW « 3-16 
MASK EVENT « 9-58 
MATCH VISUAL INFO « 5-10 
MOVE RESIZE WINDOW « 3-36 
MOVE WINDOW « 3-36 
NEXT EVENT « 9-57 
NEXT REQUEST « 9-63 
OPEN DISPLAY « 2-3 
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Routines (Cont.) 
PEEK EVENT « 9-57 
PEEK IF EVENT «9-58 
PENDING « 9-57 
POLYGON REGION « 6-24 
PUT BACK EVENT * 9-59 
PUT IMAGE « 7-9 
QUERY BEST CURSOR «6-37 
QUERY BEST SIZE « 4-9 
QUERY COLOR ¢ 5-26 
QUERY POINTER ¢ 3-42 
QUERY TEXT EXTENTS * 8-18 
QUERY TEXT EXTENTS 16 «8-18 
QUERY TREE « 3-42 
RAISE WINDOW « 3-39 
requiring protocol requests * B—1 
RESIZE WINDOW « 3-36 
RESTACK WINDOW «3-39 
SELECT INPUT + 9-5 
SEND EVENT « 9-59 
SET ERROR ROUTINE « 9-60 
SET FONT « 8-15 
SET IO ERROR HANDLER « 9-62 
SET SELECTION OWNER « 3-30 
SET WINDOW BORDER WIDTH « 3-36 
SET WM HINTS « 3-25 
STORE COLOR « 5-25 
STORE COLORS « 5-25 
STORE NAMED COLOR « 5-25 
SYNC * 9-63 
SYNCHRONIZE « 9-59 
TEXT EXTENTS « 8-18 
TEXT EXTENTS 16 «8-18 
TEXT WIDTH « 8-18 . 
TEXT WIDTH 16° 8-18 
UNDEFINE CURSOR ° 6-38 
UNINSTALL COLORMAP ° 5-4 
UNMAP SUBWINDOWS « 3-17 
UNMAP WINDOW ¢ 3-17 
WINDOW EVENT « 9-58 


S 


Save under operation 
definition * 3-11 
effect of changing «3-41 
Screen 
specifying display * 2~3 
updating pixel values + 4-4 
Segment data structure » 6~8 
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SELECT INPUT routine « 9-5 
Selection 
See Window selection 
Selection clear event data structure » 9-53 
Selection event data structure * 9-55 
Selection request event data structure * 9-54 
SEND EVENT routine * 9-59 
Server 
client requests to * 1-9 
definition * 1-1 
managing requests * 2-8 
relationship to client *2—1 
Server access control list 
definition «2-5 
Server Natural Form 
See SNF 
SET ERROR HANDLER routine » 9-60 
SET FONT routine * 8-15 . 
SET IO ERROR HANDLER routine * 9-62 
SET SELECTION OWNER routine « 3-30 
Set window attributes data structure * 3-8, 3-9 
SET WINDOW BORDER WIDTH routine ¢ 3-36 
SET WM HINTS routine * 3-25 
Size hints data structure « 3-29 
SNF (Server Natural Form) * A—1 
Stacking order 
changing * 3-38 to 3-39 
Static color + 5-6 
Static gray * 5-6 
Stippling 
- origin for *4—10 
specifying pixmap for «4-10 
STORE COLOR routine * 5-25 
STORE COLORS routine * 5~—25 
STORE NAMED COLOR routine « 5-25 
Subwindow 
lowering * 3-39 
mapping * 3-16 
movement when reconfiguring parent + 3-36 
raising * 3-39 
reordering in hierarchy * 3-16 
SYNCHRONIZE routine * 9~59 
Synchronous operation * 9-59 
SYNC routine * 9-63 


T 


Text 
computing size of * 8-18 





Text (Cont.) 
drawing » 8-18 
example of drawing with DRAW STRING « 8-21 
example of drawing with DRAW TEXT « 8-20 
styles of filling » 4-8 
text character 
definition * 8—1 
illustrated + 8—1 
positioning * 8—1 
TEXT EXTENTS 16 routine * 8-18 
TEXT EXTENTS routine « 8-18 
Text item 16 data structure « 8-19 
Text item data structure * 8-18 
TEXT WIDTH 16 routine * 8-18 
TEXT WIDTH routine * 8-18 
Tiling 
origin for » 4—10 
specifying pixmap for « 4—9 
Transport mechanism « 2-3 
True color «5-6 


UNDEFINE CURSOR routine * 6-38 
UNINSTALL COLORMAP routine « 5-4 
Unmap event data structure * 9-47 


UNMAP SUBWINDOWS routine * 3-17 
UNMAP WINDOW routine + 3-17 


V 


Visibility event data structure » 9-48 
Visual info data structure « 5-8, 5-9 
Visual type 

definition » 5-5 

determining « 5-8 

direct color * 5-6 

gray scale «5-5 

pseudocolor « 5—5 

static color « 5-6 

static gray «5-6 

true color * 5-6 

using to share color * 5-5 
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Window 
associating properties with «3-17 
changing 
attributes «3-39 to 3-41 
characteristics of * 3-31 
stacking orders 3-38 to 3-39 
circulation 
receiving notification of * 9-37 
clearing areas of * 6-23 
clearing areas with FILL RECTANGLES « 6-23 
copying areas of * 6-24 
creating 
receiving notification of * 9-40 
using attributes of parent + 3-6 
creating and specifying attributes of * 3-7 to 3-16 
creating simple *3-6 to 3-7 
default characteristics » 3-6 
destroying * 3-16 
receiving notification of * 9-414 
entries and exits «9-15 
example of configuring * 3~33 
example of creating simple * 3—7 
example of mapping and raising in hierarchy « 
3-16 
flags for referring to attributes * 3-13 
getting information about * 3-41 to 3-44 
initial state 
providing window manager hints about » 3-25 
lowering in the hierarchy * 3-39 
mapping * 3-16 
receiving notification of «9-43 
obscuring * 3-5 
treating * 3-11 
overview of + 3-1 
parent 
definition * 3-2 
receiving notification of change of * 9-45 
position relative to parent «3-4 
raising in the hierarchy * 3-39 
reconfiguration 
effects on graphics and text * 3-36 
resizing * 3-31 
restacking 
constants for specifying * 3-32 
restoring contents of exposed * 9-28 
saving contents of another * 3-11 
specifying background color of * 4—4 
specifying color maps for * 3-12 


Index—9. 


Index 


Window (Cont.) 

- specifying cursor for * 3-12 
specifying foreground color of * 4—4 
types of «3-1 
unmapping * 3-16 

receiving notification of «9-47 
visibility of * 3-5 
receiving notification of change in * 9-48 
Window attribute 
data structure used to define * 3-8 
default value of «3-12 
defining * 3-7 to 3-16 
Window attributes data structure * 3-42, 3-43 
Window background 
effect of changing * 3-41 
repainting * 3—41 
server treatment of * 3-9 
specifying when creating a window «3-6 to 3-7, 
3-9 to 3-10 
using a pixel to define * 3-10 
using a pixmap to define » 3-9 
Window border 
effect of changing * 3-41 
effect on graphic operations » 3-10 
specifying when creating a window * 3-6 to 3-7, 
3-10 
using a pixel to define «3-10 
using a pixmap to define «3-10 
Window changes data structure « 3-32 
Window clipping 
specifying * 4—10 
Window contents 
managing when window is resized ¢ 3-11 
preserving * 3-11 
repainting when obscured * 3-11 
saving * 3-11 
Window coordinate system * 3-4 to 3-5 
Window entry or exit 
caused by a grab * 9-18 
caused by pointer movement» 9-18 
events reported as result of * 9-18 
example of handling » 9-19 
pseudomotion * 9—21 
Window event 
See Event 
WINDOW EVENT routine » 9-58 
Window exposure * 9-28 to 9-30 
definition * 9-28 
example of handling » 9-30 
Window gravity 
definition * 3-11 
effect of changing * 3-41 
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Window hierarchy * 3-2 to 3-4 
Window icon 
providing window manager hints about « 3-25 
Window manager 
providing hints to * 3-24 
working with + 3-24 
Window movement 
managing when parent is resized * 3—11 
Window obscuring * 3-5 
treating « 3-11 
Window occlusion « 3-5 
Window position 
receiving notification of change in * 9-42 
specifying when creating a window «3-6 to 3-7 
Window restacking * 3-39 
Window selection 
definition * 3-30 
receiving notification of 9-53 
receiving notification of request for * 9-55 
receiving request to convert * 9-54 
Window size 
specifying when creating a window *3-6 to 3-7 
Window visibility * 3-5 
See also Mapping 
receiving notification of changes in * 9-48 
WM hints data structure * 3-26 


X 


Xlib program 

sample of « 1-2 
XY bitmap format * 7-9 
XY pixmap format + 7—9 


Z 


Z pixmap format * 7~9 
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Technical Support 


If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing 


your electronic, telephone, or direct mail order. 


Electronic Orders 


To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud 
modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Your Location Call 


Continental USA, 800-DIGITAL 
Alaska, or Hawaii 


Puerto Rico 809-754-7575 
Canada 800-267-6215 
International 

Internal! 


Contact 


Digital Equipment Corporation 
P.O. Box CS2008 
Nashua, New Hampshire 03061 


Local Digital subsidiary 


Digital Equipment of Canada 

Attn: DECdirect Operations KAOQ2/2 
P.O. Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 


Local Digital subsidiary or 

approved distributor 

USASSB Order Processing - WMO/E15 
or 

U.S. Area Software Supply Business 
Digital Equipment Corporation 
Westminster, Massachusetts 01473 


1¥or internal orders, you must submit an Internal Software Order Form (EN-01740-07). 
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Please use this postage-paid form to comment on this manual. If you require a written reply to a software 
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your 
comments on an SPR form. 


Thank you for your assistance. 


I rate this manual’s: Excellent Good Fair Poor 


Accuracy (software works as manual says) 
Completeness (enough information) 
Clarity (easy to understand) 

Organization (structure of subject matter) 
Figures (useful) 

_ Examples (useful) 

Index (ability to find topic) 

Page layout (easy to find information) 
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